Accéder aux tables Azure Databricks à partir de clients Apache Iceberg

Le catalogue REST Apache Iceberg permet aux clients pris en charge, tels qu’Apache Spark, Apache Flink et Trino, de lire et d’écrire dans des tables Iceberg inscrites dans Unity Catalog sur Azure Databricks.

Pour obtenir la liste complète des intégrations prises en charge, consultez intégrations du catalogue Unity.

Utiliser le point de terminaison du catalogue Iceberg d’Unity Catalog

Unity Catalog fournit une implémentation de la spécification de l’API de catalogue REST Iceberg.

Configurez l’accès à l’aide du point de terminaison /api/2.1/unity-catalog/iceberg-rest. Consultez la spécification de l’API REST Iceberg pour plus d’informations sur l’utilisation de cette API REST.

Spécifications

Azure Databricks prend en charge l’accès au catalogue REST d'Iceberg pour les tables dans le cadre du Unity Catalog. Le catalogue Unity doit être activé dans votre espace de travail pour utiliser ces points de terminaison. Les types de tableau suivants sont accessibles via le catalogue REST Iceberg :

Les tables iceberg étrangères ne sont pas automatiquement actualisées lors de la lecture via l’API du catalogue REST Iceberg. Pour actualiser, vous devez exécuter REFRESH FOREIGN TABLE pour lire la dernière capture instantanée. La distribution d’informations d’identification sur les tables Iceberg étrangères n’est pas prise en charge.

Vous devez suivre les étapes de configuration suivantes pour configurer l’accès en lecture ou en écriture à des tables Azure Databricks à partir de clients Iceberg à l’aide du catalogue REST Iceberg :

• Activez l’Accès à des données externes pour votre metastore. Voir Activation de l'accès aux données externes sur le métastore.
• Accordez au principal configurant l'intégration le privilège EXTERNAL USE SCHEMA sur le schéma contenant les tables. Consultez Accorder des privilèges de catalogue Unity principaux.
• Authentifiez-vous à l’aide d’un jeton d’accès personnel Azure Databricks ou d’OAuth. Consultez Autoriser l’accès aux ressources Azure Databricks.

Utiliser des tables Iceberg avec Apache Spark

Voici un exemple de configuration d’Apache Spark pour accéder aux tables Azure Databricks via l’API du catalogue REST Iceberg à l’aide de l’authentification 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"

Remplacez les variables suivantes :

• <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
• <spark-catalog-name>: nom que vous souhaitez affecter au catalogue dans votre session Spark.
• <workspace-url>: URL de l’espace de travail Azure Databricks.
• <oauth_client_id> : ID client OAuth pour le principal d’authentification.
• <oauth_client_secret> : secret client OAuth pour le principal d’authentification.

Avec ces configurations, vous pouvez interroger des tables dans le catalogue Unity à l’aide d’Apache Spark. Pour accéder aux tables sur plusieurs catalogues, vous devez configurer chaque catalogue séparément.

Lorsque vous interrogez des tables dans le catalogue Unity à l’aide de configurations Spark, gardez à l’esprit ce qui suit :

• Vous avez besoin de "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" uniquement si vous exécutez des procédures stockées spécifiques à Iceberg.

• Azure Databricks utilise le stockage d’objets cloud pour toutes les tables. Vous devez ajouter le fichier JAR iceberg-spark-runtime en tant que packages Spark :

  • AWS : org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
  • Azure : org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
  • BPC : org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

  Pour plus d’informations, consultez la documentation relative à l’intégration d’Iceberg AWS pour Spark.

  Remarque

  Ces configurations ne sont pas requises lors de l’accès aux tables Iceberg à partir d’Azure Databricks. Le chargement de JARs Iceberg externes sur des clusters Azure Databricks n’est pas pris en charge.

Accéder aux tables Azure Databricks avec Snowflake

Voici un exemple des paramètres de configuration de Snowflake pour accéder aux tables Azure Databricks en vous connectant au catalogue REST Iceberg dans Unity Catalog :

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;

Remplacez les variables suivantes :

• <catalog-integration-name>: Le nom que vous souhaitez attribuer au catalogue enregistré auprès de Snowflake.
• <uc-schema-name>: nom du schéma dans le catalogue Unity auquel vous devez accéder.
• <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
• <workspace-url>: URL de l’espace de travail Azure Databricks.
• <token>: jeton PAT pour le principal configurant l’intégration.

Utiliser des tables Azure Databricks avec PyIceberg

Voici un exemple des paramètres de configuration permettant à PyIceberg d’accéder aux tables Azure Databricks en se connectant au catalogue REST Iceberg dans le catalogue Unity :

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

Remplacez les variables suivantes :

• <workspace-url>: URL de l’espace de travail Azure Databricks.
• <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
• <token>: jeton PAT pour le principal configurant l’intégration.

Consultez la documentation relative à la configuration du catalogue REST PyIceberg.

Exemple curl de l’API REST

Vous pouvez également utiliser un appel d’API REST comme celui de cet exemple curl pour charger une table :

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>

Vous devez ensuite recevoir une réponse semblable à ceci :

{
  "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>"
  }
}