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 le catalogue Unity sur Azure Databricks.

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

Remarque

Unity Catalog dispose également d'un point de terminaison d'API de catalogue REST Iceberg en lecture seule. Il s’agit d’un point de terminaison hérité. Consultez Lire des tables Databricks à partir de clients Apache Iceberg (version héritée).

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.

Remarque

Azure Databricks a introduit la vente d’informations d’identification pour certains clients de lecteur Iceberg. Databricks recommande d’utiliser la distribution d’informations d’identification pour contrôler l’accès aux emplacements de stockage cloud pour les systèmes pris en charge. Consultez La distribution des informations d’identification de Unity Catalog pour l’accès aux systèmes externes et Accéder aux tables Iceberg à l’aide de systèmes externes.

Si la distribution des informations d’identification n’est pas prise en charge pour votre client, vous devez configurer l’accès du client à l’emplacement de stockage contenant les fichiers et les métadonnées de la table Delta ou Iceberg. Pour plus d’informations sur la configuration, reportez-vous à la documentation de votre client Iceberg.

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 à l’aide du catalogue REST Iceberg :

Sujet Lire Écrire
Table Iceberg gérée Oui Oui
Table Iceberg étrangère Oui Non
Delta géré (avec les lectures Iceberg activées) Oui Non
Delta externe (avec Iceberg Reads activés) Oui Non

Les tables iceberg étrangères ne sont pas automatiquement actualisées lors de l’utilisation de l’API du catalogue REST Iceberg pour lire les tables. 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.

Remarque

Vous devez configurer des tables Delta pour qu’elles soient accessibles à l’aide de l’API du catalogue REST Iceberg. Consultez lire les tables Delta Lake avec les clients Iceberg à l’aide de UniForm.

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

Remarque

La spécification Iceberg n’autorise pas les fichiers de données en doublons dans un instantané de table unique. Pour éviter cela, lorsqu’il est détecté, Unity Catalog empêche les moteurs externes de valider des fichiers de données en double dans la table.

Remarque

Pour lire des tables avec des filtres de lignes ou des masques de colonne attachés à partir d’un client Iceberg externe, consultez les contrôles d’accès basés sur les attributs (ABAC) cross-engine pour connaître les versions et la configuration requises du client.

Utiliser des tables Iceberg avec Apache Spark

Les exemples suivants montrent comment configurer Apache Spark pour accéder aux tables Azure Databricks via l’API du catalogue REST Iceberg. Azure Databricks prend en charge l’authentification OAuth et l’authentification par jeton d’accès personnel (PAT).

Pour accéder aux tables sur plusieurs catalogues, vous devez configurer chaque catalogue séparément.

Remarque

Vous devez inclure le fichier JAR du runtime Iceberg Spark et le fichier JAR d’offre groupée spécifique au cloud dans vos packages Spark. La version JAR du runtime doit correspondre à vos versions Spark et Scala. Par exemple, pour Spark 3.5 avec Scala 2.12 :

  • org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>

Plus l’offre groupée spécifique au cloud :

  • 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. Ces fichiers JAR ne sont pas nécessaires pour accéder aux tables Iceberg depuis des clusters Azure Databricks.

Authentification OAuth

Interface de ligne de commande (CLI)

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.rest.auth.type=oauth2" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri=https://<workspace-url>/oidc/v1/token" \
  --conf "spark.sql.catalog.<spark-catalog-name>.credential=<oauth_client_id>:<oauth_client_secret>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.scope=all-apis"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.rest.auth.type", "oauth2") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.oauth2-server-uri", "https://<workspace-url>/oidc/v1/token") \
    .config("spark.sql.catalog.<spark-catalog-name>.credential", "<oauth_client_id>:<oauth_client_secret>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .config("spark.sql.catalog.<spark-catalog-name>.scope", "all-apis") \
    .getOrCreate()

Remplacez les variables suivantes :

  • <spark-catalog-name>: nom que vous souhaitez affecter au catalogue dans votre session Spark.
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
  • <oauth_client_id> : ID client OAuth pour le principal d’authentification.
  • <oauth_client_secret> : secret client OAuth pour le principal d’authentification.
  • <iceberg-version>: La version d’Iceberg à utiliser, par exemple 1.9.2.

Authentification PAT

Interface de ligne de commande (CLI)

pyspark \
  --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version> \
  --conf "spark.sql.catalog.<spark-catalog-name>=org.apache.iceberg.spark.SparkCatalog" \
  --conf "spark.sql.catalog.<spark-catalog-name>.type=rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.uri=https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest" \
  --conf "spark.sql.catalog.<spark-catalog-name>.token=<token>" \
  --conf "spark.sql.catalog.<spark-catalog-name>.warehouse=<uc-catalog-name>"

Python

from pyspark.sql import SparkSession

spark = SparkSession.builder \
    .config("spark.jars.packages", "org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:<iceberg-version>,org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>") \
    .config("spark.sql.catalog.<spark-catalog-name>", "org.apache.iceberg.spark.SparkCatalog") \
    .config("spark.sql.catalog.<spark-catalog-name>.type", "rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.uri", "https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest") \
    .config("spark.sql.catalog.<spark-catalog-name>.token", "<token>") \
    .config("spark.sql.catalog.<spark-catalog-name>.warehouse", "<uc-catalog-name>") \
    .getOrCreate()

Remplacez les variables suivantes :

  • <spark-catalog-name>: nom que vous souhaitez affecter au catalogue dans votre session Spark.
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
  • <token> : Un jeton d’accès personnel (PAT) pour le principal qui s’authentifie. Consultez Authentifier avec les jetons d'accès personnel d'Azure Databricks (obsolete).
  • <iceberg-version>: La version d’Iceberg à utiliser, par exemple 1.9.2.

Accéder aux tables Azure Databricks avec Snowflake

Snowflake propose deux options d’accès aux tables via le catalogue REST Iceberg : à l’aide des bases de données liées au catalogue de Snowflake ou à l’aide de tables externes.

Pour les deux options, commencez par configurer une intégration de catalogue Snowflake. Azure Databricks prend en charge les méthodes d’authentification suivantes pour les intégrations de catalogue Snowflake :

  • Jeton du porteur : utilise un jeton d’accès personnel Azure Databricks (PAT) ou OAuth. Pris en charge sur tous les clouds.
  • Entra service principal OAuth (Azure uniquement) : utilise un principal de service Microsoft Entra ID pour s’authentifier directement auprès du point d'accès de jeton Entra.

Pour plus d’informations sur les options d’authentification Snowflake pour les intégrations de catalogue REST, consultez la documentation Snowflake.

Snowflake avec authentification par jeton porteur

L’exemple suivant configure une intégration de catalogue Snowflake à l’aide d’un jeton du porteur. Vous pouvez utiliser un jeton d’accès personnel Azure Databricks (PAT) ou un jeton OAuth généré à partir d’un principal de service Azure Databricks. Pour plus d’informations sur la génération de jetons OAuth, consultez Autoriser l’accès des identités de service à Azure Databricks avec OAuth.

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. Par exemple, https://cust-success.cloud.databricks.com ou https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: jeton d’accès personnel (PAT) pour la personne principale configurant l’intégration.

Snowflake avec le principal de service Entra OAuth

Sur Azure, les intégrations de catalogue Snowflake qui utilisent un principal de service pris en charge par Entra ne peuvent pas utiliser le point de terminaison de jeton OIDC Azure Databricks (<workspace-url>/oidc/v1/token). Au lieu de cela, vous devez vous authentifier directement contre l'endpoint de jeton Microsoft Entra. Cela diffère de l’approche OAuth utilisée pour d’autres clients Iceberg (tels qu’Apache Spark) sur Azure.

Remarque

La documentation de Snowflake peut indiquer que l’ID Entra n’est pas pris en charge. La configuration ci-dessous utilise Entra OAuth pour accéder à l'étendue de ressources Azure Databricks, et constitue la méthode prise en charge pour lire Unity Catalog depuis Snowflake sur Azure.

Avant de commencer, assurez-vous d’avoir :

Exécutez le code SQL suivant dans Snowflake :

CREATE OR REPLACE CATALOG INTEGRATION <catalog-integration-name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = 'https://<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    WAREHOUSE = '<uc-catalog-name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://login.microsoftonline.com/<azure-tenant-id>/oauth2/v2.0/token'
    OAUTH_CLIENT_ID = '<entra-client-id>'
    OAUTH_CLIENT_SECRET = '<entra-client-secret>'
    OAUTH_ALLOWED_SCOPES = ('2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default')
  )
  ENABLED = TRUE
  REFRESH_INTERVAL_SECONDS = 600;

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. Par exemple : adb-1234567890123456.12.azuredatabricks.net.
  • <azure-tenant-id> : Votre identifiant de tenant Microsoft Entra.
  • <entra-client-id> : l'ID d'application (client) du principal de service Entra.
  • <entra-client-secret>: secret client pour le principal de service Entra.

Importante

L’étendue 2ff814a6-3304-4ab8-85cb-cd0e6f879c1d/.default est l’ID d'application Azure Databricks enregistré dans Entra. Cela est distinct de l’étendue all-apis utilisée avec le point de terminaison OIDC Azure Databricks. L’utilisation de l’étendue incorrecte est une cause courante des échecs d’authentification lors de la configuration de cette intégration.

Après avoir créé l’intégration du catalogue, suivez la documentation Snowflake pour créer une base de données liée au catalogue pour accéder à vos tables.

Pour plus d’informations sur la création et la gestion des principaux de service Entra pour Azure Databricks, consultez Authentifier auprès des principaux de service Microsoft Entra.

Remarque

Snowflake ne prend pas en charge l’authentification Entra pour les intégrations de catalogue qui utilisent la mise en réseau privée (Azure Private Link) pour se connecter à Azure Databricks. La connexion au point de terminaison du catalogue REST d’Azure Databricks Iceberg doit utiliser la mise en réseau publique lors de l’authentification auprès d’un principal de service Entra.

Bases de données liées au catalogue

Les bases de données liées au catalogue de Snowflake sont automatiquement synchronisées avec Unity Catalog pour détecter les schémas et les tables Iceberg. Cela élimine la nécessité d’actualiser manuellement les métadonnées.

Après avoir configuré une intégration de catalogue Snowflake, reportez-vous à la documentation Snowflake pour créer une base de données liée au catalogue pour accéder à vos tables.

Importante

La tentative d’écriture à partir de Snowflake dans des tables Azure Databricks en lecture seule peut entraîner des erreurs. Reportez-vous à la documentation Snowflake pour les opérations prises en charge.

Tables externes

Vous pouvez également créer des tables externes après avoir créé une intégration de catalogue Snowflake. Cette approche nécessite l’actualisation manuelle des métadonnées pour afficher les mises à jour.

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = '<catalog-integration-name>'
  CATALOG_TABLE_NAME = '<uc-table-name>';

Utiliser des tables Azure Databricks avec PyIceberg

Pour utiliser PyIceberg pour accéder aux tables Azure Databricks, vous devez installer PyIceberg avec les dépendances requises. PyIceberg nécessite pyarrow des opérations de table telles que la lecture de données et l’inspection des métadonnées de table. Installez PyIceberg avec l’option pyarrow supplémentaire :

pip install "pyiceberg[pyarrow]"

Remarque

Si vous n’installez pyarrowpas, les opérations telles que la description ou la lecture des tables échouent. Pour obtenir la liste complète des dépendances facultatives, consultez la documentation 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 :

  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity auquel vous devez accéder.
  • <token>: jeton d’accès personnel (PAT) pour la personne principale configurant l’intégration.

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

Exemple curl de l’API REST

L’exemple suivant curl charge une table à l’aide de l’API REST :

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>

La réponse ressemble à 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>"
  }
}

Remarque

Le expires-at-ms champ indique à quel moment les informations d’identification expirent. La durée d’expiration par défaut est d’une heure. Pour de meilleures performances, le client met en cache les informations d’identification jusqu’à ce qu’elles expirent avant de demander de nouvelles informations.

  • Last updated on