Aller au contenu principal
Dernière mise à jour le

Accéder aux tables Databricks depuis les 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 les tables Iceberg enregistrées dans Unity Catalog sur Databricks.

Pour une liste complète des intégrations prises en charge, consultez les intégrations Unity Catalog.

remarque

Unity Catalog dispose également d’un endpoint d'API REST Catalog Iceberg en lecture seule. Il s'agit d'un endpoint hérité. Voir Lire les tables Databricks à partir de clients Apache Iceberg (hérité).

Utilisez l'endpoint de catalogue Iceberg d'Unity Catalog​

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

Configurez l'accès à l'aide de l'endpoint /api/2.1/unity-catalog/iceberg-rest. Consultez la spécification de l'API REST Iceberg pour plus de détails sur l'utilisation de cette API REST.

remarque

Databricks a introduit la fourniture d'identifiants pour certains clients lecteurs Iceberg. Databricks recommande d'utiliser la fourniture d'identifiants pour contrôler l'accès aux emplacements de stockage cloud pour les systèmes pris en charge. Consultez Provisionnement d'informations d'identification Unity Catalog pour l'accès aux systèmes externes et Accès aux tables Iceberg à l'aide de systèmes externes.

Si la distribution d'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 pour la table Delta ou Iceberg. Reportez-vous à la documentation de votre client Iceberg pour les détails de configuration.

Exigences​

Databricks prend en charge l'accès au catalogue Iceberg REST aux tables dans le cadre de Unity Catalog. Vous devez avoir Unity Catalog activé dans votre Workspace pour utiliser ces Endpoints. Les types de table suivants sont accessibles via l’Iceberg REST Catalog :

Sujet

Lire l'article

Écriture

Géré Iceberg

Oui

Oui

Iceberg étranger

Oui

Non

Delta géré (avec lectures Iceberg activées)

Oui

Non

Delta externe (avec lectures Iceberg activées)

Oui

Non

Sujet

Lire l'article

Écriture

Géré Iceberg

Oui

Oui

Iceberg étranger

Oui

Non

Delta géré (avec lectures Iceberg activées)

Oui

Non

Delta externe (avec lectures Iceberg activées)

Oui

Non

Les tables Iceberg externes ne sont pas automatiquement rafraîchies lorsque l'API Iceberg REST Catalog est utilisée pour lire les tables. To refresh, vous devez exécuter REFRESH FOREIGN TABLE pour lire le dernier instantané. La distribution d'informations d'identification sur les tables Iceberg étrangères n'est pas prise en charge.

remarque

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

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

remarque

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

remarque

Pour lire les tables avec des filtres de ligne ou des masques de colonne attachés à partir d'un client Iceberg externe, consultez la section Contrôles d'accès basés sur les attributs inter-moteurs (ABAC) pour connaître les versions et la configuration client requises.

Utilisez des tables Iceberg avec Apache Spark​

Les exemples suivants montrent comment configurer Apache Spark pour accéder aux tables Databricks via l'API REST Catalog Iceberg. Databricks prend en charge l'authentification OAuth et par jetons d’accès personnels (PAT).

Pour accéder à des tables dans plusieurs catalogues, vous devez configurer chaque catalogue séparément.

remarque

Vous devez inclure le JAR d'exécution Iceberg Spark et le JAR de bundle spécifique au cloud dans vos packages Spark. La version du 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 le bundle spécifique au cloud :

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

Pour plus de détails, consultez la documentation relative à l'intégration d'Iceberg AWS pour Spark. Ces JAR ne sont pas nécessaires lors de l'accès aux tables Iceberg à partir des clusters Databricks.

Lors de la lecture des tables sur AWS, le client Iceberg utilise le SDK AWS et requiert une région explicite. Avant de lancer Spark, définissez la région en utilisant soit la variable d'environnement AWS_REGION, soit la configuration Spark spark.hadoop.fs.s3a.region. Sans cela, les analyses échouent lors de l'exécution avec Unable to load region from any of the providers in the chain.

Bash
export AWS_REGION=us-west-2

Authentification OAuth​

Bash
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"

Remplacez les variables suivantes :

  • <spark-catalog-name>: le nom que vous souhaitez attribuer au catalogue dans votre session Spark.

  • <uc-catalog-name>: le nom du catalogue dans Unity Catalog 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 Iceberg à utiliser, par exemple 1.9.2.

  • <workspace-url>: l'URL du workspace Databricks. Par exemple, cust-success.cloud.databricks.com.

Authentification PAT​

Bash
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>"

Remplacez les variables suivantes :

  • <spark-catalog-name>: le nom que vous souhaitez attribuer au catalogue dans votre session Spark.

  • <uc-catalog-name>: le nom du catalogue dans Unity Catalog qui contient vos tables.

  • <token>: Un jeton d'accès personnel (PAT) pour le mandant d'authentification. Consultez S'authentifier avec les jetons d'accès personnels Databricks (hérité).

  • <iceberg-version>: La version Iceberg à utiliser, par exemple 1.9.2.

  • <workspace-url>: l'URL du workspace Databricks. Par exemple, cust-success.cloud.databricks.com.

Accéder aux tables Databricks avec Snowflake​

Snowflake propose deux options pour accéder aux tables via le catalogue REST Iceberg : en utilisant les bases de données liées au catalogue de Snowflake, ou en utilisant des tables externes.

Pour les deux options, configurez d'abord une intégration de catalogue Snowflake. Databricks prend en charge les méthodes d'authentification suivantes pour les intégrations de catalogues Snowflake :

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

Pour plus de détails 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 porteur. Vous pouvez utiliser un jeton d'accès personnel Databricks (PAT) ou un jeton OAuth généré à partir d'un Service Principal Databricks. Pour plus de détails sur la génération des jetons OAuth, consultez Autoriser l'accès du Service Principal à Databricks avec OAuth.

SQL
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;

Remplacez les variables suivantes :

  • <catalog-integration-name>: Le nom que vous souhaitez attribuer au catalogue enregistré dans Snowflake.
  • <uc-schema-name>: le nom du schéma dans Unity Catalog auquel vous devez accéder.
  • <uc-catalog-name>: le nom du catalogue dans Unity Catalog auquel vous devez accéder.
  • <workspace-url>: l'URL du workspace Databricks. Par exemple, https://cust-success.cloud.databricks.com ou https://adb-1234567890123456.12.azuredatabricks.net.
  • <token>: Un jeton d'accès personnel (PAT) pour le principal configurant l'intégration.

Bases de données liées au catalogue​

Les bases de données liées au catalogue de Snowflake se synchronisent automatiquement avec Unity Catalog pour détecter les schémas et les tables Iceberg. Ceci élimine le besoin de refresh manuel des métadonnées.

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

important

Toute tentative d'écriture de Snowflake vers des tables Databricks en lecture seule peut entraîner des erreurs. Référez-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 d’actualiser manuellement les métadonnées pour voir les mises à jour.

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

Utiliser les tables Databricks avec PyIceberg​

Pour utiliser PyIceberg afin d'accéder aux tables Databricks, vous devez installer PyIceberg avec les dépendances requises. PyIceberg requiert pyarrow pour les Opérations de table telles que la lecture de données et l'inspection des métadonnées de table. Installez PyIceberg avec le complément pyarrow :

Bash
pip install "pyiceberg[pyarrow]"
remarque

Si vous n'installez pas pyarrow, les opérations telles que la description ou la lecture des tables échouent. Pour la liste complète des dépendances facultatives, consultez la documentation PyIceberg.

Vous trouverez ci-dessous un exemple de paramètres de configuration permettant à PyIceberg d'accéder aux tables Databricks en se connectant au catalogue REST Iceberg dans Unity Catalog :

YAML
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>: l'URL du workspace Databricks. Par exemple, cust-success.cloud.databricks.com.

  • <uc-catalog-name>: le nom du catalogue dans Unity Catalog auquel vous devez accéder.

  • <token>: Un jeton d'accès personnel (PAT) pour le principal configurant l'intégration.

Consultez la documentation pour la configuration du catalogue REST PyIceberg.

Exemple de curl pour l'API REST​

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

Bash
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 se présente comme suit :

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

Le champ expires-at-ms indique quand les identifiants expirent. Le default expiration time est d'une heure. Pour de meilleures performances, faites en sorte que le client mette en cache les identifiants jusqu'à leur expiration avant d'en demander de nouveaux.

Sur cette page