Partager via

Utiliser UniForm pour lire les tables Delta avec les clients Iceberg

  • Article

Le format universel Delta (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é.

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 comme s’il s’agissait de tables Iceberg. Une seule copie des fichiers de données sert les deux formats.

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 utilise zstd 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.

Configuration requise

Pour activer UniForm, vous devez remplir les conditions suivantes :

Remarque

Vous ne pouvez pas activer des vecteurs de suppression sur une table sans l’activation d’UniForm. Lors de l’activation d’UniForm sur une table existante avec des vecteurs de suppression activés, UniForm désactive et supprime définitivement des vecteurs de suppression et réécrit des fichiers de données, le cas échéant.

Activer Delta UniForm

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. Vous ne pouvez pas désactiver le mappage de colonnes une fois qu’il a été activé, et les mises à niveau vers les versions du protocole de lecteur et d’enregistreur Delta Lake ne peuvent pas être annulées.

Vous devez définir les propriétés de table suivantes pour activer la prise en charge d’UniForm pour Iceberg :

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

Vous devez également activer le mappage de colonnes pour utiliser UniForm. Il est activé automatiquement si vous activez UniForm 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');

Vous pouvez activer UniForm sur une table existante en utilisant la syntaxe suivante :

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

Remarque

Cette syntaxe fonctionne également pour une mise à niveau à partir de la version de préversion publique d’UniForm qui utilisant la fonctionnalité de table IcebergCompatV1.

Cette syntaxe désactive automatiquement et supprime définitivement des vecteurs de suppression dans la table. Les fichiers existants sont réécrits, le cas échéant, pour les rendre compatibles avec 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.

Remarque

Si vous envisagez d’utiliser BigQuery comme client de lecteur Iceberg, vous devez définir spark.databricks.delta.write.dataFilesToSubdir sur true sur Azure Databricks pour répondre à une exigence BigQuery pour la disposition des données.

Voir Limitations.

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

Azure Databricks déclenche la génération de métadonnées Iceberg de manière asynchrone une fois qu’une transaction d’écriture Delta Lake est terminée à l’aide du même calcul que celui qui a terminé la transaction Delta. 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 Iceberg, les tables Delta avec des validations fréquentes peuvent regrouper plusieurs commits Delta en un seul commit Iceberg.

Delta Lake garantit qu’un seul processus de génération de métadonnées Iceberg est en cours à tout moment. Les validations qui déclencheraient un deuxième processus de génération de métadonnées Iceberg simultané seront validées 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.

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. Vous devez configurer l’accès au stockage d’objets cloud sous-jacent contenant la table Delta avec UniForm activé. Pour plus d’informations sur la configuration, reportez-vous à la documentation relative au client lecteur Iceberg.

Vous devez générer et configurer un jeton d’accès personnel Azure Databricks pour permettre à d’autres services de se connecter à Unity Catalog. Consultez Authentification pour l’automatisation d’Azure Databricks : vue d’ensemble.

Voici un exemple des paramètres permettant de 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.catalog-impl": "org.apache.iceberg.rest.RESTCatalog",
"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.io-impl": "org.apache.iceberg.aws.s3.S3FileIO

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>.

Remarque

Lors de l’interrogation de tables dans Unity Catalog à l’aide de cette méthode, les identificateurs d’objet utilisent le modèle suivant :

unity.<catalog-name>.<schema-name>.<table-name>

Ce modèle utilise les mêmes noms à trois niveaux namespacing présent dans Unity Catalog, mais ajoute un préfixe unitysupplémentaire .

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 Iceberg et Delta ne s’alignent pas sur l’horodatage de validation ou l’ID de version. Si vous souhaitez 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 définies sur la table Iceberg. Consultez Vérifier les états de génération de métadonnées Iceberg.

Limites

Les limites suivantes existent :

  • 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é.

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.

Certaines fonctionnalités de table Delta Lake utilisées par UniForm ne sont pas prises en charge par des clients de lecteur Delta Sharing. Consultez Partager des données et des ressources IA de façon sécurisée à l’aide du partage Delta.