Compartir vía

Acceso a tablas de Azure Databricks desde clientes de Apache Iceberg

Importante

Unity Catalog Apache Iceberg REST Catalog API está en Public Preview en Databricks Runtime 16.4 LTS y superior. Este punto de conexión se recomienda para leer y escribir en tablas utilizando clientes de Iceberg.

El catálogo de Unity también tiene un punto de conexión de la API de Catálogo REST Iceberg de solo lectura. Se trata de un punto de conexión heredado. Consulte Lectura de tablas de Databricks de clientes de Apache Iceberg (heredados).

El catálogo REST de Apache Iceberg permite a los clientes admitidos, como Apache Spark, Apache Flink y Trino, leer y escribir en tablas registradas en el Unity Catalog en Azure Databricks.

Para obtener una lista completa de las integraciones admitidas, consulte Integraciones del catálogo de Unity.

Utilice el punto final del catálogo Iceberg de Unity Catalog

El catálogo de Unity proporciona una implementación de la especificación de la API del catálogo REST de Iceberg.

Configure el acceso mediante el punto de conexión /api/2.1/unity-catalog/iceberg-rest. Vea la especificación de la API REST de Iceberg para obtener más detalles sobre el uso de esta API REST.

Nota

Azure Databricks ha introducido la distribución de credenciales para algunos clientes lectores de Iceberg. Databricks recomienda usar la provisión de credenciales para controlar el acceso a las ubicaciones de almacenamiento en la nube en los sistemas compatibles. Consulte Provisión de credenciales de Unity Catalog para el acceso a sistemas externos.

Si no se admite la distribución de credenciales para el cliente, debe configurar el acceso desde el cliente a la ubicación de almacenamiento que contiene los archivos y metadatos de la tabla Delta o Iceberg. Consulte la documentación para el cliente de Iceberg para obtener más información sobre la configuración.

Requisitos

Azure Databricks admite el acceso al catálogo REST de Iceberg para las tablas como parte de Unity Catalog. Debe tener habilitado el catálogo de Unity en el área de trabajo para usar estos puntos de conexión. Se puede acceder a los siguientes tipos de tabla a través del catálogo REST de Iceberg:

Tema Lectura Escribir
Iceberg administrado Sí Sí
Iceberg Extranjero Sí No
Managed Delta (con lecturas Iceberg habilitadas) Sí No
External Delta (con lecturas Iceberg habilitadas) Sí No

Las tablas Iceberg externas no se actualizan automáticamente al leer a través de la API de catálogo REST de Iceberg. Para actualizar, debe ejecutar REFRESH FOREIGN TABLE para leer la instantánea más reciente. No se admite la venta de credenciales en tablas Foreign Iceberg.

Nota

Debe configurar las tablas Delta para que sean accesibles a través de la API de catálogo REST de Iceberg. Consulte Leer tablas Delta con clientes de Iceberg.

Debe completar los siguientes pasos de configuración para configurar el acceso para leer o escribir en tablas de Azure Databricks desde clientes de Iceberg mediante el catálogo REST de Iceberg:

Uso de tablas de Iceberg con Apache Spark

A continuación se muestra un ejemplo de cómo configurar Apache Spark para acceder a las tablas de Azure Databricks a través de la API del catálogo REST de Iceberg mediante la autenticación de OAuth:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables in Unity Catalog
"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"

Reemplace las siguientes variables:

  • <uc-catalog-name>: El nombre del catálogo en Unity Catalog que contiene tus tablas.
  • <spark-catalog-name>: el nombre que desea asignar al catálogo en la sesión de Spark.
  • <workspace-url>: la dirección URL del área de trabajo de Azure Databricks.
  • <oauth_client_id>: ID de cliente OAuth para la entidad de seguridad autenticadora.
  • <oauth_client_secret>: Secreto de cliente OAuth para la entidad de seguridad autenticadora.

Con estas configuraciones, puede consultar tablas en el catálogo de Unity mediante Apache Spark. Para acceder a tablas en varios catálogos, debe configurar cada catálogo por separado.

Al consultar tablas en el catálogo de Unity mediante configuraciones de Spark, tenga en cuenta lo siguiente:

  • Solo necesita "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" si ejecuta procedimientos almacenados específicos de Iceberg.

  • Azure Databricks usa el almacenamiento de objetos en la nube para todas las tablas. Debe agregar el JAR iceberg-spark-runtime como paquetes de Spark.

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Celeste: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Para más detalles, consulte la documentación de la integración de Iceberg con AWS para Spark.

    Nota

    Estas configuraciones no son necesarias al acceder a las tablas de Iceberg desde Azure Databricks. No se admite la carga de JARs externos de Iceberg en clústeres de Azure Databricks.

Acceso a tablas de Azure Databricks con Snowflake

A continuación se muestra un ejemplo de las opciones de configuración para que Snowflake acceda a las tablas de Azure Databricks mediante la conexión al catálogo REST de Iceberg en el catálogo de Unity:

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>'
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<token>'
  )
  ENABLED = TRUE;

Reemplace las siguientes variables:

  • <catalog-integration-name>: el nombre que desea asignar al catálogo registrado en Snowflake.
  • <uc-schema-name>: el nombre del esquema en el catálogo de Unity al que debe acceder.
  • <uc-catalog-name>: el nombre del catálogo en el catálogo de Unity al que debe tener acceso.
  • <workspace-url>: la dirección URL del área de trabajo de Azure Databricks.
  • <token>: Token PAT para el principal responsable de configurar la integración.

Uso de tablas de Azure Databricks con PyIceberg

A continuación se muestra un ejemplo de las opciones de configuración para permitir que PyIceberg acceda a las tablas de Azure Databricks mediante la conexión al catálogo REST de Iceberg en el catálogo de Unity:

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

Reemplace las siguientes variables:

  • <workspace-url>: la dirección URL del área de trabajo de Azure Databricks.
  • <uc-catalog-name>: el nombre del catálogo en el catálogo de Unity al que debe tener acceso.
  • <token>: Token PAT para el principal responsable de configurar la integración.

Consulte la documentación de la configuración del catálogo REST de PyIceberg.

Ejemplo de CURL de la API de REST

También puede usar una llamada a la API de REST como la de este ejemplo de curl para cargar una tabla:

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>

A continuación, debería recibir una respuesta similar a la siguiente:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Nota

El campo expires-at-ms de la respuesta indica la hora de expiración de las credenciales y tiene una hora de expiración predeterminada de una hora. Para mejorar el rendimiento, haga que el cliente almacene en caché las credenciales hasta la fecha de expiración antes de solicitar una nueva.

  • Last updated on