Utiliser UniForm pour lire les tables Delta avec les clients Iceberg

  • Article

Le format universel Delta Lake (UniForm) vous permet de lire des tables Delta avec des clients de lecteur Iceberg. Cette fonctionnalité requiert Databricks Runtime 14.3 LTS ou version ultérieure.

Important

Pour découvrir la documentation de la fonctionnalité de table IcebergCompatV1 UniForm héritée, voir UniForm IcebergCompatV1 hérité.

Vous pouvez configurer une connexion externe pour qu’Unity Catalog fasse office de catalogue Iceberg. Consultez Lire à l’aide du point de terminaison du catalogue Unity Catalog Iceberg.

UniForm Iceberg utilise Zstandard plutôt que Snappy comme codec de compression pour les fichiers de données Parquet sous-jacents.

Remarque

La génération de métadonnées UniForm s’exécute de manière asynchrone sur le calcul utilisé pour écrire des données dans des tables Delta, ce qui peut augmenter l’utilisation des ressources du pilote.

Fonctionnement d’UniForm

UniForm tire parti du fait que Delta Lake et Iceberg se composent de fichiers de données Parquet et d’une couche de métadonnées. UniForm génère automatiquement les métadonnées Iceberg de manière asynchrone, sans réécrire les données, afin que les clients Iceberg puissent lire les tables Delta. Une seule copie des fichiers de données sert plusieurs formats.

Spécifications

Pour activer UniForm Iceberg, les exigences suivantes doivent être remplies :

Remarque

Vous ne pouvez pas activer des vecteurs de suppression sur une table sans l’activation d’UniForm Iceberg.

Utilisez REORG pour désactiver et vider les vecteurs de suppression en activant UniForm Iceberg sur une table existante avec des vecteurs de suppression activés. Consultez Activer ou mettre à niveau à l’aide de REORG.

Activer UniForm Iceberg

Important

L’activation de Delta UniForm définit la fonctionnalité de table Delta IcebergCompatV2, une fonctionnalité de protocole d’écriture. Seuls les clients qui prennent en charge cette fonctionnalité de table peuvent écrire dans des tables avec UniForm. Vous devez utiliser Databricks Runtime 14.3 LTS ou version ultérieure pour écrire dans des tables Delta avec cette fonctionnalité activée.

Vous pouvez désactiver UniForm en désactivant la propriété de delta.universalFormat.enabledFormats table. Les changements de niveau des versions des protocoles de lecteur et d’écrivain de Delta Lake ne peuvent pas être annulés.

Vous devez définir les propriétés de table suivantes pour activer UniForm pour Iceberg :

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

Lorsque vous activez UniForm pour la première fois, la génération de métadonnées asynchrones commence. Cette tâche doit se terminer avant que les clients externes puissent interroger la table à l’aide d’Iceberg. Consultez Vérifier les états de génération de métadonnées Iceberg.

Pour obtenir la liste des limitations, consultez Limitations.

Activer lors de la création d’une table

Mappage de colonnes doit être activé pour utiliser UniForm Iceberg. Cela se fait automatiquement si vous activez UniForm Iceberg lors de la création d’une table, comme dans l’exemple suivant :

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Activer en modifiant une table existante

Dans Databricks Runtime 15.4 LTS et versions ultérieures, vous pouvez activer ou mettre à niveau UniForm Iceberg sur une table existante à l’aide de la syntaxe suivante :

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

Activer ou mettre à niveau à l’aide de REORG

Vous pouvez utiliser REORG pour activer UniForm Iceberg et réécrire les fichiers de données sous-jacents, comme dans l’exemple suivant :

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

Utilisez REORG si vous vous trouvez dans l’un de ces cas :

  • Des vecteurs de suppression sont activés dans votre table.
  • Vous avez précédemment activé la version IcebergCompatV1 d’UniForm Iceberg.
  • Vous devez lire à partir de moteurs Iceberg qui ne prennent pas en charge les fichiers Parquet de style Hive, tels qu’Athena ou Redshift.

Quand UniForm génère-t-il des métadonnées Iceberg ?

Azure Databricks déclenche la génération de métadonnées de manière asynchrone après la fin d’une transaction d’écriture Delta Lake. Ce processus de génération de métadonnées utilise le même calcul que celui qui a terminé la transaction Delta.

Remarque

Vous pouvez également déclencher manuellement la génération de métadonnées Iceberg. Consultez Déclencher manuellement la conversion de métadonnées Iceberg.

Pour éviter les latences d’écriture associées à la génération de métadonnées, les tables Delta avec des validations fréquentes peuvent regrouper plusieurs validations Delta en une seule validation aux métadonnée Iceberg.

Delta Lake garantit qu’un seul processus de génération de métadonnées Iceberg est en cours à tout moment sur une ressource de calcul donnée. Les validations qui déclencheraient un deuxième processus de génération de métadonnées simultané se valident avec succès sur Delta, mais elles ne déclenchent pas la génération asynchrone de métadonnées Iceberg. Cela évite la latence en cascade pour la génération de métadonnées pour les charges de travail avec des validations fréquentes (de secondes à minutes entre les validations).

Consultez Versions de la table Delta et Iceberg.

Versions de la table Delta et Iceberg

Delta Lake et Iceberg autorisent les requêtes de voyage dans le temps à l’aide de versions de table ou d’horodatages stockés dans les métadonnées de table.

En général, les versions de table Delta ne s’alignent pas sur les versions Iceberg par l’horodatage de validation ou l’ID de version. Pour vérifier à quelle version d’une table Delta correspond une version donnée d’une table Iceberg, vous pouvez utiliser les propriétés de table correspondantes. Consultez Vérifier les états de génération de métadonnées Iceberg.

Vérifier les états de génération de métadonnées Iceberg

UniForm ajoute les champs suivants aux métadonnées de table Unity Catalog et Iceberg pour suivre les états de génération de métadonnées :

Champ métadonnées Description
converted_delta_version Dernière version de la table Delta pour laquelle les métadonnées Iceberg ont été générées avec succès.
converted_delta_timestamp Horodatage du dernier commit Delta pour lequel les métadonnées Iceberg ont été générées avec succès.

Sur Azure Databricks, vous pouvez passer en revue ces champs de métadonnées en effectuant l’un des éléments suivants :

  • Passer en revue la section Delta Uniform Iceberg retournée par DESCRIBE EXTENDED table_name.
  • Passer en revue les métadonnées de table avec l’Explorateur de catalogues.
  • Utiliser l’API REST pour obtenir une table.

Consultez la documentation de votre client de lecteur Iceberg pour savoir comment passer en revue les propriétés de table en dehors d’Azure Databricks. Pour OSS Apache Spark, vous pouvez voir ces propriétés à l’aide de la syntaxe suivante :

SHOW TBLPROPERTIES <table-name>;

Déclencher manuellement la conversion de métadonnées Iceberg

Vous pouvez déclencher manuellement la génération de métadonnées Iceberg pour la dernière version de la table Delta. Cette opération s’exécute de manière synchrone, ce qui signifie qu’une fois terminée, le contenu de la table disponible dans Iceberg reflète la dernière version de la table Delta disponible au démarrage du processus de conversion.

Cette opération ne doit pas être nécessaire dans des conditions normales, mais peut vous aider si vous rencontrez les éléments suivants :

  • Un cluster se termine avant que la génération automatique de métadonnées ne réussisse.
  • Une erreur ou un échec de travail interrompt la génération de métadonnées.
  • Un client qui ne prend pas en charge la géneration des métadonnées UniForm Iceberg écrit dans la table Delta.

Utilisez la syntaxe suivante pour déclencher manuellement la génération de métadonnées Iceberg :

MSCK REPAIR TABLE <table-name> SYNC METADATA

Consultez REPAIR TABLE.

Lecture à l’aide d’un chemin JSON de métadonnées

Certains clients Iceberg nécessitent que vous fournissiez un chemin d’accès aux fichiers de métadonnées versionnés pour inscrire des tables Iceberg externes. Chaque fois qu’UniForm convertit une nouvelle version de la table Delta en Iceberg, il crée un fichier JSON de métadonnées.

Les clients qui utilisent des chemins JSON de métadonnées pour la configuration d’Iceberg incluent BigQuery. Pour plus d’informations sur la configuration, reportez-vous à la documentation relative au client lecteur Iceberg.

Delta Lake stocke les métadonnées Iceberg sous le répertoire de la table, selon le modèle suivant :

<table-path>/metadata/<version-number>-<uuid>.metadata.json

Sur Azure Databricks, vous pouvez passer en revue cet emplacement de métadonnées en effectuant l’une des opérations suivantes :

  • Passer en revue la section Delta Uniform Iceberg retournée par DESCRIBE EXTENDED table_name.
  • Passer en revue les métadonnées de table avec l’Explorateur de catalogues.
  • Utiliser la commande suivante avec l’API REST :
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

La réponse inclut les informations suivantes :

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

Important

Les clients de lecteur Iceberg basés sur un chemin d’accès peuvent nécessiter la mise à jour et l’actualisation manuelles des chemins JSON des métadonnées pour lire les versions de table actuelles. Les utilisateurs peuvent rencontrer des erreurs lors de l’interrogation de tables Iceberg à l’aide de versions obsolètes, car les fichiers de données Parquet sont supprimés de la table Delta avec VACUUM.

Lire à l’aide du point de terminaison du catalogue Unity Catalog Iceberg

Certains clients Iceberg peuvent se connecter à un catalogue REST Iceberg. Unity Catalog fournit une implémentation en lecture seule de l’API du catalogue REST Iceberg pour les tables Delta avec UniForm activé à l’aide du point de terminaison /api/2.1/unity-catalog/iceberg. Consultez la spécification de l’API REST Iceberg pour plus d’informations sur l’utilisation de cette API REST.

Les clients connus pour prendre en charge l’API du catalogue Iceberg incluent Apache Spark, Flink et Trino. Pour plus d’informations sur la configuration, reportez-vous à la documentation relative au client lecteur Iceberg.

Authentification et autorisation

Il existe deux conditions requises pour accéder aux données inscrites dans Unity Catalog à l’aide du point de terminaison api/2.1/unity-catalog/iceberg à partir de services externes :

Exemple de configuration Apache Spark

Voici un exemple des paramètres utilisé pour configurer OSS Apache Spark pour lire UniForm comme Iceberg :

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.type": "rest",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token": "<your_personal_access_token>",
"spark.sql.catalog.unity.warehouse": "<uc_catalog_name>"

Remplacez l’URL complète de l’espace de travail dans lequel vous avez généré le jeton d’accès personnel pour <api-root>.

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

  • Les identificateurs d’objet utilisent le modèle unity.<schema-name>.<table-name>.

    Ce modèle utilise le même espace de noms à trois niveaux utilisé dans le Unity Catalog, mais avec le nom du catalogue remplacé par unity.

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

  • Si vous utilisez un fournisseur de cloud pour le stockage, vous devez ajouter les jars de bundle Iceberg spécifiques au cloud en tant que packages Spark :

    • 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 d’informations, consultez la documentation relative à l’intégration d’Iceberg AWS pour Spark.

Exemple de curl d’API REST

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

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

La réponse doit alors ressembler à 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 champ expires-at-ms de la réponse indique le délai d’expiration des informations d’identification est réglé par défaut sur une heure. Pour de meilleures performances, faites en sorte que le client mette en cache les informations d’identification jusqu’au moment de l’expiration avant de faire une nouvelle demande.

Limites

Les limitations suivantes existent pour toutes les tables UniForm :

  • UniForm ne fonctionne pas sur les tables avec des vecteurs de suppression activés. Consultez Que sont les vecteurs de suppression ?.
  • Les tables Delta avec UniForm activé ne prennent pas en charge les types VOID.
  • Les clients Iceberg peuvent uniquement lire à partir d’UniForm. Les écritures ne sont pas prises en charge.
  • Les clients de lecteur Iceberg peuvent avoir des limitations individuelles, indépendamment d’UniForm. Consultez la documentation relative au client que vous avez choisi.
  • Les destinataires de Delta Sharing peuvent uniquement lire la table en tant que Delta, même lorsque UniForm est activé.
  • Certaines fonctionnalités de table Delta Lake utilisées par UniForm Iceberg ne sont pas prises en charge par des clients de lecteur Delta Sharing. Consultez Présentation de Delta Sharing.

Le flux des changements de données fonctionnent pour les clients Delta lorsqu’UniForm est activé, mais n’a pas de prise en charge dans Iceberg.