Utiliser des tables Iceberg avec OneLake

Dans Microsoft OneLake, vous pouvez travailler en toute transparence avec des tables aux formats Delta Lake et Apache Iceberg.

Cette flexibilité est activée par le biais de la virtualisation des métadonnées, une fonctionnalité qui permet aux tables Iceberg d’être interprétées comme des tables Delta Lake, et inversement. Vous pouvez écrire directement des tables Iceberg ou créer des raccourcis vers ces tables, ce qui rend ces tables accessibles dans différentes charges de travail Fabric. De même, les tables Fabric écrites au format Delta Lake peuvent être lues à l’aide de lecteurs Iceberg.

Lorsque vous écrivez ou créez un raccourci vers un dossier de table Iceberg, OneLake génère automatiquement des métadonnées Delta Lake virtuelles (journal Delta) pour la table, ce qui permet son utilisation avec les charges de travail Fabric. À l’inverse, les tables Delta Lake incluent désormais des métadonnées iceberg virtuelles, ce qui permet la compatibilité avec les lecteurs Iceberg.

Diagramme montrant la virtualisation de table d’Iceberg vers Delta Lake.

Bien que cet article inclut des conseils sur l’utilisation des tables Iceberg avec Snowflake, cette fonctionnalité est destinée à travailler avec toutes les tables Iceberg avec des fichiers de données au format Parquet dans le stockage.

Virtualiser les tables Delta Lake en tant qu’Iceberg

Pour configurer la conversion automatique et la virtualisation des tables du format Delta Lake au format Iceberg, procédez comme suit.

Important

Cette fonctionnalité est en préversion.

Activez la virtualisation automatique des tables Delta Lake au format Iceberg en activant le paramètre OneLake délégué nommé Enable Delta Lake to Apache Iceberg table virtualization in your workspace settings.

Remarque

Ce paramètre contrôle une fonctionnalité actuellement en préversion. Ce paramètre sera supprimé dans une prochaine mise à jour lorsque la fonctionnalité est activée pour tous les utilisateurs et n’est plus en préversion.
Assurez-vous que votre table Delta Lake, ou un raccourci vers celui-ci, se trouve dans la Tables section de votre élément de données. L’élément de données peut être un lakehouse ou un autre élément de données Fabric.

Conseil / Astuce

Si votre lakehouse est activé avec un schéma, alors votre répertoire de table se trouve directement dans un schéma tel que dbo. Si votre lakehouse n'est pas compatible avec le schéma, votre répertoire de tables se trouve directement dans le répertoire Tables.
Vérifiez que votre table Delta Lake a été convertie avec succès au format Iceberg virtuel. Pour ce faire, examinez le répertoire derrière la table.

Pour afficher le répertoire si votre table se trouve dans un lakehouse, vous pouvez cliquer avec le bouton droit sur la table dans l’interface utilisateur fabric et sélectionner Afficher les fichiers.

Si votre table se trouve dans un autre type d’élément de données, tel qu’un entrepôt, une base de données ou une base de données mise en miroir, vous devez utiliser un client comme l’Explorateur Stockage Azure ou l’Explorateur de fichiers OneLake, plutôt que l’interface utilisateur Fabric, pour afficher les fichiers derrière la table.
Vous devez voir un répertoire nommé metadata à l’intérieur du dossier de table, et il doit contenir plusieurs fichiers, y compris le fichier journal de conversion. Ouvrez le fichier journal de conversion pour afficher plus d’informations sur la conversion Delta Lake to Iceberg, y compris l’horodatage de la conversion la plus récente et les détails des erreurs.
Si le fichier journal de conversion indique que la table a été correctement convertie, lisez la table Iceberg à l’aide de votre service, application ou bibliothèque de choix.

Selon le lecteur Iceberg que vous utilisez, vous devez connaître le chemin d’accès au répertoire de table ou au fichier le plus récent .metadata.json affiché dans le metadata répertoire.

Vous pouvez voir le chemin HTTP vers le dernier fichier de métadonnées de votre table en ouvrant la vue Propriétés du *.metadata.json fichier avec le numéro de version le plus élevé. Prenez note de ce chemin d’accès.

Le chemin vers le dossier de l'élément de données Tables peut ressembler à ceci :
```
https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
```
Dans ce dossier, le chemin relatif du fichier de métadonnées le plus récent peut ressembler à dbo/MyTable/metadata/321.metadata.json.

Pour lire votre table iceberg virtuelle à l’aide de Snowflake, suivez les étapes décrites dans ce guide.

Créer un raccourci de table vers une table Iceberg

Si vous disposez déjà d’une table Iceberg dans un emplacement de stockage pris en charge par les raccourcis OneLake, effectuez ces étapes pour créer un raccourci et faire apparaître votre table Iceberg au format Delta Lake.

Localisez votre table Iceberg. Recherchez l’emplacement de stockage de votre table Iceberg, qui peut se trouver dans Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage ou un service de stockage compatible S3.

Remarque

Si vous utilisez Snowflake et que vous ne savez pas où votre table Iceberg est stockée, vous pouvez exécuter l’instruction suivante pour voir l’emplacement de stockage de votre table Iceberg.

SELECT SYSTEM$GET_ICEBERG_TABLE_INFORMATION('<table_name>');

L’exécution de cette instruction retourne un chemin d’accès au fichier de métadonnées de la table Iceberg. Ce chemin d’accès vous indique quel compte de stockage contient la table Iceberg. Par exemple, voici les informations pertinentes pour trouver le chemin d’une table Iceberg stockée dans Azure Data Lake Storage :

{"metadataLocation":"azure://<storage_account_path>/<path_within_storage>/<table_name>/metadata/00001-389700a2-977f-47a2-9f5f-7fd80a0d41b2.metadata.json","status":"success"}

Votre dossier de table Iceberg doit contenir un dossier metadata, qui contient lui-même au moins un fichier se terminant par .metadata.json.
Dans votre lakehouse Fabric, créez un raccourci de table dans la zone Tables du lakehouse.

Conseil / Astuce

Si vous voyez des schémas tels que dbo sous le dossier Tables de votre lakehouse, alors le lakehouse prend en charge les schémas. Dans ce cas, cliquez avec le bouton droit sur le schéma et créez un raccourci de table sous le schéma.
Pour le chemin d’accès cible de votre raccourci, sélectionnez le dossier de la table Iceberg. Le dossier de la table Iceberg contient les dossiers metadata et data.
Une fois votre raccourci créé, cette table devrait être reflétée automatiquement en tant que table Delta Lake dans votre lakehouse, prête à être utilisée dans Fabric.

Si votre nouveau raccourci de table Iceberg n’apparaît pas comme une table utilisable, consultez la section Résolution des problèmes.

Dépannage

Les conseils suivants peuvent vous aider à garantir la compatibilité de vos tables Iceberg avec cette fonctionnalité :

Vérifier la structure de dossiers de votre table Iceberg

Ouvrez votre dossier Iceberg dans l’outil d’explorateur de stockage de votre choix, puis vérifiez la liste des répertoires de votre dossier Iceberg dans son emplacement d’origine. Vous devez voir une structure de dossiers comme celle de l’exemple suivant.

../
|-- MyIcebergTable123/
    |-- data/
        |-- A5WYPKGO_2o_APgwTeNOAxg_0_1_002.parquet
        |-- A5WYPKGO_2o_AAIBON_h9Rc_0_1_003.parquet
    |-- metadata/
        |-- 00000-1bdf7d4c-dc90-488e-9dd9-2e44de30a465.metadata.json
        |-- 00001-08bf3227-b5d2-40e2-a8c7-2934ea97e6da.metadata.json
        |-- 00002-0f6303de-382e-4ebc-b9ed-6195bd0fb0e7.metadata.json
        |-- 1730313479898000000-Kws8nlgCX2QxoDHYHm4uMQ.avro
        |-- 1730313479898000000-OdsKRrRogW_PVK9njHIqAA.avro
        |-- snap-1730313479898000000-9029d7a2-b3cc-46af-96c1-ac92356e93e9.avro
        |-- snap-1730313479898000000-913546ba-bb04-4c8e-81be-342b0cbc5b50.avro

Si vous ne voyez pas le dossier de métadonnées, ou si vous ne voyez pas de fichiers avec les extensions indiquées dans cet exemple, il se peut que vous n’ayez pas de table Iceberg générée correctement.

Vérifier le journal de conversion

Lorsqu’une table Iceberg est virtualisée en tant que table Delta Lake, un dossier nommé _delta_log/ se trouve à l’intérieur du dossier de raccourci. Ce dossier contient les métadonnées du format Delta Lake (le journal Delta) après la conversion réussie.

Ce dossier inclut également le fichier latest_conversion_log.txt, qui contient les détails relatifs à la réussite ou à l’échec de la dernière tentative de conversion.

Pour afficher le contenu de ce fichier après avoir créé votre raccourci, ouvrez le menu du raccourci de la table Iceberg sous la zone Tables de votre lakehouse et sélectionnez Afficher les fichiers.

Capture d’écran de l’élément de menu Afficher les fichiers.

Vous devez voir une structure comme celle de l’exemple suivant :

Tables/
|-- MyIcebergTable123/
    |-- data/
        |-- <data files>
    |-- metadata/
        |-- <metadata files>
    |-- _delta_log/   <-- Virtual folder. This folder doesn't exist in the original location.
        |-- 00000000000000000000.json
        |-- latest_conversion_log.txt   <-- Conversion log with latest success/failure details.

Ouvrez le fichier journal de conversion pour afficher les détails relatifs à l’heure ou à l’échec de la dernière conversion. Si vous ne voyez pas de fichier journal de conversion, cela signifie que la conversion n’a pas été tentée.

Si la conversion n’a pas été tentée

Si vous ne voyez pas de fichier journal de conversion, cela signifie que la conversion n’a pas été tentée. Voici deux raisons courantes pour lesquelles la conversion n’est pas tentée :

Le raccourci n’a pas été créé au bon endroit.

Pour qu’un raccourci vers une table Iceberg soit converti au format Delta Lake, il doit être placé directement sous le dossier Tables d’un lakehouse sans schéma. Vous ne devez pas placer le raccourci dans la section Fichiers ou sous un autre dossier si vous souhaitez que la table soit automatiquement virtualisée en tant que table Delta Lake.
Le chemin d’accès cible du raccourci n’est pas le chemin d’accès du dossier Iceberg.

Lorsque vous créez le raccourci, le chemin d’accès du dossier que vous sélectionnez dans l’emplacement de stockage cible doit uniquement être le dossier de la table Iceberg. Ce dossier contient les dossiers metadata et data.

Message d’erreur « La région de capacité de l'architecture ne peut pas être validée » dans Snowflake

Si vous utilisez Snowflake pour écrire une nouvelle table Iceberg dans OneLake, le message d’erreur suivant peut s’afficher :

La région de capacité du fabric ne peut pas être validée. Motif : « Jeton d’accès non valide. Cela peut être dû à l’authentification et à la délimitation. Vérifiez les étendues déléguées.

Si vous voyez cette erreur, demandez à votre administrateur du locataire Fabric de vérifier que vous avez activé les deux paramètres de locataire mentionnés dans la section Write an Iceberg table to OneLake using Snowflake :

Dans le coin supérieur droit de l’interface utilisateur fabric, ouvrez Paramètres, puis sélectionnez Portail d’administration.
Sous Paramètres du locataire, dans la section Paramètres du développeur, activez le paramètre intitulé Les principaux de service peuvent utiliser les API Fabric.
Dans la même zone, dans la section Paramètres OneLake , activez le paramètre étiqueté Utilisateurs pouvant accéder aux données stockées dans OneLake avec des applications externes à Fabric.

Limitations et considérations

Gardez à l’esprit les limitations temporaires suivantes lorsque vous utilisez cette fonctionnalité :

Types de données prises en charge

Les types de données de colonne Iceberg suivants sont mappés à leurs types Delta Lake correspondants à l’aide de cette fonctionnalité.

Type de colonne Iceberg	Type de colonne Delta Lake	Commentaires
`int`	`integer`
`long`	`long`	Consultez Problème de largeur de type.
`float`	`float`
`double`	`double`	Consultez Problème de largeur de type.
`decimal(P, S)`	`decimal(P, S)`	Consultez Problème de largeur de type.
`boolean`	`boolean`
`date`	`date`
`timestamp`	`timestamp_ntz`	Le type de données Iceberg `timestamp` ne contient pas d’informations de fuseau horaire. Le type Delta Lake `timestamp_ntz` n’est pas entièrement pris en charge dans les charges de travail Fabric. Nous vous recommandons d’utiliser des horodatages avec des fuseaux horaires inclus.
`timestamptz`	`timestamp`	Dans Snowflake, pour utiliser ce type, spécifiez `timestamp_ltz` comme type de colonne lors de la création de la table Iceberg. Vous trouverez ici plus d’informations sur les types de données Iceberg pris en charge dans Snowflake.
`string`	`string`
`binary`	`binary`
`time`	N/A	Non prise en charge

Problème de largeur de type

Si vous utilisez Snowflake pour écrire votre table Iceberg et que la table contient des types de colonnes INT64, double ou Decimal avec précision >= 10, il se peut que la table Delta Lake virtuelle résultante ne soit pas consommable par tous les moteurs Fabric. Des erreurs telles que la suivante peuvent s’afficher :
```
Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
```
Nous recherchons une solution à ce problème.

Solution de contournement : Si vous utilisez l’interface utilisateur d’aperçu de la table Lakehouse et que vous voyez ce problème, vous pouvez résoudre cette erreur en basculant vers l’affichage de point de terminaison SQL (en haut à droite, sélectionnez l’affichage Lakehouse et basculez vers le point de terminaison SQL) et en affichant un aperçu de la table à partir de là. Si vous revenez ensuite à l’affichage de Lakehouse, l’aperçu de table doit s’afficher correctement.

Si vous exécutez un notebook ou un travail Spark et que vous rencontrez ce problème, vous pouvez résoudre cette erreur en définissant la configuration Spark spark.sql.parquet.enableVectorizedReader sur false. Voici un exemple de commande PySpark à exécuter dans un notebook Spark :
```
spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
```
Le stockage des métadonnées de table iceberg n’est pas portable

Les fichiers de métadonnées d’une table Iceberg se font référence les uns aux autres à l’aide de références de chemins d’accès absolus. Si vous copiez ou déplacez le contenu du dossier d’une table Iceberg vers un autre emplacement sans réécrire les fichiers de métadonnées Iceberg, la table devient illisible par les lecteurs Iceberg, y compris cette fonctionnalité OneLake.

Solution de contournement :

Si vous devez déplacer votre table Iceberg vers un autre emplacement pour utiliser cette fonctionnalité, utilisez l’outil qui a écrit initialement la table Iceberg pour écrire une nouvelle table Iceberg à l’emplacement souhaité.
Les dossiers de table Iceberg ne doivent contenir qu’un seul ensemble de fichiers de métadonnées

Si vous supprimez et recréez une table Iceberg dans Snowflake, les fichiers de métadonnées ne sont pas nettoyés. Ce comportement est intentionnel, pour prendre en charge la fonctionnalité UNDROP dans Snowflake. Toutefois, étant donné que votre raccourci pointe directement vers un dossier et que ce dossier comporte désormais plusieurs ensembles de fichiers de métadonnées, nous ne pouvons pas convertir la table tant que vous n’avez pas supprimé les fichiers de métadonnées de l’ancienne table.

La conversion échoue si plusieurs fichiers de métadonnées sont trouvés dans le dossier de métadonnées de la table Iceberg.

Solution de contournement :

Pour veiller à ce que la table convertie reflète la version correcte de la table :
- Vérifiez que vous ne stockez pas plusieurs tables Iceberg dans le même dossier.
- Nettoyez tout contenu d’un dossier de table Iceberg après l’avoir supprimé, avant de recréer la table.
Les modifications apportées aux métadonnées ne sont pas immédiatement reflétées

Si vous apportez des modifications de métadonnées à votre table Iceberg, telles que l’ajout d’une colonne, la suppression d’une colonne, le changement de nom d’une colonne ou la modification d’un type de colonne, la table peut ne pas être reconvertie tant qu’une modification de données (comme l’ajout d’une ligne de données) n’a pas été apportée.

Nous travaillons sur un correctif qui récupère le fichier de métadonnées le plus récent qui inclut la dernière modification des métadonnées.

Solution de contournement :

Après avoir effectué la modification du schéma de votre table Iceberg, ajoutez une ligne de données ou apportez toute autre modification aux données. Après cette modification, vous devriez être en mesure d’actualiser et d’afficher la vue la plus récente de votre table dans Fabric.
Limitation relative à la disponibilité régionale

Cette fonctionnalité n’est pas encore disponible dans les régions suivantes :
- Qatar Centre
- Norvège Ouest
Solution de contournement :

Les espaces de travail attachés aux capacités Fabric dans d’autres régions peuvent utiliser cette fonctionnalité. Consultez la liste complète des régions où Microsoft Fabric est disponible.
Les liaisons privées ne sont pas prises en charge

Cette fonctionnalité n’est actuellement pas prise en charge pour les locataires ou les espaces de travail pour lesquels les liaisons privées sont activées.

Nous travaillons à une amélioration pour supprimer cette limitation.
Les raccourcis OneLake doivent être dans la même région

Il existe une limitation temporaire concernant l’utilisation de cette fonctionnalité avec des raccourcis qui pointent vers des emplacements OneLake : l’emplacement cible du raccourci doit se trouver dans la même région que le raccourci lui-même.

Nous travaillons à une amélioration afin de supprimer cette exigence.

Solution de contournement :

Si vous avez un raccourci OneLake vers une table Iceberg dans un autre lakehouse, vérifiez que l’autre lakehouse est associé à une capacité dans la même région.
Certains types de transformation de partition Iceberg ne sont pas pris en charge

Actuellement, les typesbucket[N] de partition Iceberg, truncate[W]et void ne sont pas pris en charge.

Si la table Iceberg en cours de conversion contient ces types de transformation de partition, la virtualisation au format Delta Lake ne réussit pas.

Nous travaillons à une amélioration pour supprimer cette limitation.

Utilisez Snowflake pour écrire ou lire des tables Iceberg dans OneLake.
En savoir plus sur Fabric et sécurité OneLake.
Apprenez-en davantage sur les raccourcis OneLake.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2025-07-02