Iceberg REST Catalog API en Databricks

La gestión de grandes volúmenes de datos en entornos distribuidos plantea desafíos importantes: diferentes motores de procesamiento, formatos de almacenamiento heterogéneos y la necesidad de mantener consistencia y trazabilidad. Apache Iceberg surge como un formato de tabla diseñado para simplificar la organización de datos en la nube, permitiendo operaciones eficientes de lectura, escritura y versionado, incluso en sistemas con múltiples clientes de análisis.

Sin embargo, para que estas tablas sean accesibles desde distintas herramientas como Apache Spark, Flink o Trino, se requiere un catálogo que funcione como intermediario entre los datos y los clientes. El Iceberg REST Catalog API, implementado en Unity Catalog de Databricks, cumple esta función, proporcionando un punto de acceso estandarizado y seguro a las tablas, facilitando la interoperabilidad y la gestión de metadatos en entornos educativos, de investigación y empresariales.

¿Qué es el Iceberg REST Catalog API?

El Iceberg REST Catalog API es la implementación del estándar de catálogos de Apache Iceberg que ofrece Databricks a través de Unity Catalog. Su función principal es proporcionar un punto de acceso unificado y basado en REST que permite a diferentes motores de procesamiento —como Apache Spark, Flink, Trino o PyIceberg— leer y, en algunos casos, escribir tablas registradas en Unity Catalog sin depender de configuraciones específicas de almacenamiento.

En lugar de interactuar directamente con los metadatos en sistemas de archivos o buckets de nube, los clientes consultan el catálogo mediante endpoints REST. Esto asegura interoperabilidad, control centralizado de permisos y manejo estandarizado de metadatos, aspectos fundamentales en arquitecturas modernas de datos distribuidos.

¿Por qué es importante el Iceberg REST Catalog API?

El principal problema que resuelve es la fragmentación de acceso a datos: antes, cada herramienta (Spark, Snowflake, Trino) requería su propia configuración para acceder a las mismas tablas.

Con el API REST de Unity Catalog:

• Una sola configuración sirve para todas las herramientas compatibles con Iceberg
• Credenciales temporales automáticas eliminan riesgos de seguridad
• Sin migración de datos - funciona con tablas Iceberg y Delta existentes

Casos de uso destacados

Estos beneficios se traducen en aplicaciones prácticas que resuelven desafíos reales en organizaciones modernas. Desde equipos que necesitan acceso desde múltiples herramientas hasta empresas que priorizan la seguridad sin sacrificar flexibilidad:

Características técnicas del Iceberg REST Catalog API

Unity Catalog implementa el estándar Iceberg REST Catalog proporcionando acceso externo a las tablas registradas en el metastore a través de endpoints REST:

Característica	Descripción	Detalles
Protocolo	Compatible con especificación Iceberg REST Catalog	Endpoints estándar /v1/catalogs, /v1/config
Autenticación	OAuth 2.0 y Personal Access Tokens (PAT)	Bearer tokens en headers HTTP
Acceso externo	Configuración requerida en Unity Catalog	Habilitación manual del metastore
Formatos soportados	Tablas Iceberg y Delta con UniForm	Lectura unificada de ambos formatos
Credential vending	Credenciales temporales automáticas	Tokens de corta duración para cloud storage
Integración	Sistema de permisos Unity Catalog	Hereda políticas de seguridad existentes

Configuración y endpoints del API

El API REST de Iceberg está disponible en la ruta base /api/2.1/unity-catalog/iceberg-rest y sigue la especificación estándar de Iceberg REST Catalog:

Endpoint	Método	Propósito
/v1/config	GET	Obtener configuración del catálogo y credenciales temporales
/v1/catalogs	GET	Listar catálogos disponibles
/v1/catalogs/{catalog}/namespaces	GET	Listar esquemas en un catálogo
/v1/catalogs/{catalog}/namespaces/{namespace}/tables	GET	Listar tablas en un esquema
/v1/catalogs/{catalog}/namespaces/{namespace}/tables/{table}	GET	Obtener metadatos de tabla específica

Configuración de seguridad y autenticación

Para habilitar el acceso externo al Iceberg REST Catalog API es necesario:

1. Habilitar acceso externo al metastore en la configuración de Unity Catalog
2. Otorgar privilegios EXTERNAL USE SCHEMA al usuario/servicio que configurará la integración
3. Configurar autenticación mediante OAuth 2.0 o Personal Access Token (PAT)
4. Definir alcance de acceso mediante el parámetro warehouse que especifica el catálogo Unity Catalog
5. Configurar credential vending para acceso seguro a los datos subyacentes

Ejemplos de uso

Apache Spark

Para que Spark acceda a las tablas de Unity Catalog mediante Iceberg REST, se requiere configurar un catálogo en la sesión de Spark:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.<spark-catalog-name>": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.rest.auth.type": "oauth2",
"spark.sql.catalog.<spark-catalog-name>.uri": "<workspace-url>/api/2.1/unity-catalog/iceberg-rest",
"spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri": "<workspace-url>/oidc/v1/token",
"spark.sql.catalog.<spark-catalog-name>.credential":"<oauth_client_id>:<oauth_client_secret>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<uc-catalog-name>",
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

Variables clave:

• <uc-catalog-name>: catálogo en Unity Catalog
• <spark-catalog-name>: nombre del catálogo en Spark
• <workspace-url>: URL del workspace Databricks
• <oauth_client_id> y <oauth_client_secret>: credenciales OAuth

Snowflake

Para acceder desde Snowflake, se configura un catalog integration que apunta al endpoint REST:

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest',
    WAREHOUSE = '<uc-catalog-name>',
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER,
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

PyIceberg

La configuración en PyIceberg es sencilla:

catalog:
  unity_catalog:
    uri: https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest
    warehouse: <uc-catalog-name>
    token: <token>

Llamadas directas con cURL

También se puede consultar tablas usando REST directamente:

curl -X GET -H "Authorization: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg-rest/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Respuesta típica:

{
  "metadata-location": "s3://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "s3.access-key-id": "<temporary-s3-access-key-id>",
    "s3.session-token":"<temporary-s3-session-token>",
    "s3.secret-access-key":"<temporary-secret-access-key>",
    "client.region":"<aws-bucket-region-for-metadata-location>"
  }
}

Conclusión

El Iceberg REST Catalog API de Unity Catalog en Databricks permite a las empresas integrar diversos clientes de análisis y procesamiento sin comprometer seguridad ni consistencia de datos. Con soporte para Spark, Snowflake, PyIceberg y cURL, es la forma recomendada de acceder a tablas Iceberg de manera programática y segura.

Recursos

• Documentación oficial de Iceberg REST Catalog API en Databricks
• Especificación Apache Iceberg REST Catalog