Accéder aux tables Databricks à partir de clients Delta

Cette page explique comment utiliser l’API REST Unity pour créer, lire et écrire dans le catalogue Unity des tables gérées et externes à partir de clients Delta externes. Pour obtenir la liste complète des intégrations prises en charge, consultez intégrations du catalogue Unity.

Conseil / Astuce

Pour plus d’informations sur la lecture des données Azure Databricks à l’aide de Microsoft Fabric, consultez Utilisez Microsoft Fabric pour lire les données inscrites dans le catalogue Unity.

Créer, lire et écrire à l’aide de l’API REST Unity

Important

La création et l’écriture dans des tables gérées par le catalogue Unity à partir de clients Delta sont en version bêta. La prise en charge des clients externes est limitée.

L’API REST Unity fournit aux clients externes l’accès en création, lecture et écriture aux tables inscrites dans le catalogue Unity. Configurez l’accès à l’aide de l’URL de l’espace de travail comme point de terminaison. Les types de tableau suivants sont accessibles :

Type de table Lire Write Créer
Delta géré Oui Oui* Oui*
Delta externe Oui Oui Oui

* Pris en charge pour les tables Delta managées avec des validations de catalogue.

Spécifications

Azure Databricks prend en charge l’accès de l’API REST Unity aux tables dans le cadre du catalogue Unity. Le catalogue Unity doit être activé dans votre espace de travail pour utiliser ces points de terminaison.

Vous devez également effectuer les étapes de configuration suivantes pour configurer l’accès aux tables à partir de clients Delta à l’aide de l’API REST Unity :

Limites

  • L’accès externe aux tables UniForm avec IcebergCompatV3 n’est actuellement pas pris en charge. Après avoir écrit en externe dans une table UniForm, vous devez exécuter MSCK REPAIR TABLE dans Databricks pour générer des métadonnées Iceberg.
  • Les modifications de schéma (par exemple, ALTER TABLE), les mises à jour des propriétés de table et les modifications des fonctionnalités de table ne sont actuellement pas prises en charge sur les tables gérées à partir de clients externes.
  • Les clients externes ne peuvent pas effectuer d’opérations de maintenance de table, telles que OPTIMIZE, VACUUMet ANALYZE, sur des tables Delta gérées.
  • Les clients externes ne peuvent pas créer de clones peu profonds.
  • Les clients externes ne peuvent pas créer de tables avec des colonnes générées, des colonnes par défaut ou des colonnes de contrainte.
  • Lors de la création de tables externes, Azure Databricks recommande d’utiliser Apache Spark pour vous assurer que les définitions de colonnes sont dans un format compatible avec Apache Spark. L’API ne valide pas la précision de la spécification de colonne. Si la spécification n’est pas compatible avec Apache Spark, Databricks Runtime peut ne pas pouvoir lire les tables.

Accéder aux tables Delta avec Apache Spark à l’aide de l’authentification PAT

La configuration suivante est nécessaire pour lire ou écrire dans les tables Delta managées et externes du catalogue Unity avec Apache Spark à l’aide de l’authentification PAT :

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Remplacez les variables suivantes :

  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contient vos tables.
  • <token>: jeton d’accès personnel (PAT) pour la personne principale configurant l’intégration.
  • <workspace-url> : URL Azure Databricks workspace, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.

Note

Les versions de package indiquées ci-dessus sont actuelles à compter de la dernière mise à jour de cette page. Des versions plus récentes peuvent être disponibles. Vérifiez que les versions de package sont compatibles avec votre version Spark.

Pour plus d’informations sur la configuration d’Apache Spark pour le stockage d’objets cloud, consultez la documentation du catalogue Unity OSS.

Important

Databricks Runtime 16.4 et versions ultérieures est nécessaire pour lire, écrire ou créer des tables avec des validations de catalogue activées. Databricks Runtime 18.0 et versions ultérieures est nécessaire pour activer ou désactiver les validations de catalogue sur les tables existantes.

Pour créer des tables Delta managées avec des validations de catalogue, utilisez le code SQL suivant :

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

Pour créer des tables Delta externes, utilisez le code SQL suivant :

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

Accéder aux tables Delta avec Apache Spark à l’aide de l’authentification OAuth

Azure Databricks prend également en charge l’authentification de machine à machine (M2M) OAuth. OAuth gère automatiquement le renouvellement des jetons et des informations d’identification pour l’authentification du catalogue Unity.

L’authentification OAuth pour les clients Spark externes nécessite :

La configuration suivante est requise pour créer, lire ou écrire dans des tables gérées par le catalogue Unity et des tables Delta externes avec Apache Spark à l’aide de l’authentification OAuth :

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Remplacez les variables suivantes :

  • <workspace-url> : URL Azure Databricks workspace, y compris l’ID de l’espace de travail. Par exemple : adb-1234567890123456.12.azuredatabricks.net.

Note

Les versions de package indiquées ci-dessus sont actuelles à compter de la dernière mise à jour de cette page. Des versions plus récentes peuvent être disponibles. Vérifiez que les versions de package sont compatibles avec votre version Spark.

Créer des tables Delta à l’aide de l’API

Pour créer une table Delta externe à l’aide de l’API REST du catalogue Unity, procédez comme suit :

Étape 1 : Effectuer une requête POST à l’API Create Table

Utilisez la demande d’API suivante pour inscrire les métadonnées de table dans le catalogue Unity :

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

Remplacez les variables suivantes :

  • <workspace-url> : URL de l’espace de travail Azure Databricks
  • <token>: Jeton pour le principal effectuant l’appel d’API
  • <uc-catalog-name>: nom du catalogue dans le catalogue Unity qui contiendra la table externe
  • <schema-name>: nom du schéma dans le catalogue où la table sera créée
  • <table-name>: Nom de la table externe
  • <path>: chemin d’accès complet aux données de table

Étape 2 : Initialiser l’emplacement de la table Delta

L’appel d’API ci-dessus inscrit la table dans :[UC], mais elle ne crée pas les fichiers Delta à l’emplacement de stockage. Pour initialiser l’emplacement de la table, écrivez une table Delta vide à l’aide de Spark :

Le schéma utilisé dans cette étape doit correspondre exactement aux définitions de colonne fournies dans la demande d’API.


from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")

Note

L’API Create Table pour les clients externes présente les limitations suivantes :

  • Seules les tables Delta externes sont prises en charge ("table_type": "EXTERNAL" et "data_source_format": "DELTA").
  • Seuls les champs suivants sont autorisés :
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • Les masques de colonne ne sont pas pris en charge.
  • Last updated on