Usare tabelle Iceberg con OneLake

In OneLake è possibile usare facilmente le tabelle in formati Delta Lake e Apache Iceberg.

Questa flessibilità è abilitata tramite la virtualizzazione dei metadati, una funzionalità che consente di interpretare le tabelle Iceberg come tabelle Delta Lake e viceversa. È possibile scrivere direttamente tabelle Iceberg o creare collegamenti a tali tabelle, rendendole accessibili in diversi carichi di lavoro di Fabric. Analogamente, le tabelle Fabric scritte nel formato Delta Lake possono essere lette usando i lettori Iceberg.

Quando si scrive o si crea un collegamento a una cartella di tabella Iceberg, OneLake genera automaticamente i metadati Delta Lake virtuali (log Delta) per la tabella, abilitandone l'uso con i carichi di lavoro Fabric. Al contrario, le tabelle Delta Lake ora includono metadati iceberg virtuali, consentendo la compatibilità con i lettori Iceberg.

Anche se questo articolo include indicazioni per l'uso di tabelle Iceberg con Snowflake, questa funzionalità è progettata per lavorare con qualsiasi tabella Iceberg con file di dati in formato Parquet nell'archiviazione.

Virtualizzare le tabelle Delta Lake come Iceberg

Per configurare la conversione automatica e la virtualizzazione delle tabelle dal formato Delta Lake al formato Iceberg, seguire questa procedura.

1. Assicurati che la tua tabella Delta Lake, o una scorciatoia per essa, si trovi nella Tables sezione del tuo elemento dati. L'elemento dati potrebbe essere una casa sul lago o un altro elemento dati Fabric.

   Suggerimento

   Se il lakehouse è dotato di schema, la directory della tabella si troverà direttamente all'interno di uno schema come dbo. Se il lakehouse non è dotato di schema, la directory della tabella sarà direttamente all'interno della directory Tables.

2. Verificare che la tabella Delta Lake sia stata convertita correttamente nel formato Iceberg. A tale scopo, esaminare la directory dietro la tabella.

   Per visualizzare la directory se la tabella si trova in una lakehouse, è possibile fare clic con il pulsante destro del mouse sulla tabella nell'interfaccia utente di Fabric e selezionare Visualizza file.

   Se la tabella si trova in un altro tipo di elemento di dati, ad esempio un warehouse, un database o un database con mirroring, è necessario usare un client come Azure Storage Explorer o OneLake File Explorer, anziché l'interfaccia utente di Fabric, per visualizzare i file dietro la tabella.

3. Dovrebbe essere visualizzata una directory denominata metadata all'interno della cartella della tabella e deve contenere più file, incluso il file di log di conversione. Aprire il file di log della conversione per visualizzare altre informazioni sulla conversione da Delta Lake a Iceberg, incluso il timestamp della conversione più recente ed eventuali dettagli sull'errore.

4. Se il file di log di conversione indica che la tabella è stata convertita correttamente, leggere la tabella Iceberg usando il servizio, l'app o la libreria desiderata.

   A seconda del lettore Iceberg utilizzato, è necessario conoscere il percorso alla directory della tabella oppure il file più recente .metadata.json, mostrato nella directory metadata.

   È possibile visualizzare il percorso HTTP del file di metadati più recente della tabella aprendo la visualizzazione Proprietà per il *.metadata.json file con il numero di versione più alto. Prendere nota di questo percorso.

   Il percorso della cartella Tables del tuo elemento di dati potrebbe essere simile a questo:

   https://onelake.dfs.fabric.microsoft.com/83896315-c5ba-4777-8d1c-e4ab3a7016bc/a95f62fa-2826-49f8-b561-a163ba537828/Tables/
   

   All'interno di quella cartella, il percorso relativo verso l'ultimo file di metadati potrebbe apparire come dbo/MyTable/metadata/321.metadata.json.

   Per leggere la tabella iceberg virtuale usando Snowflake, seguire la procedura descritta in questa guida.

Creare un collegamento rapido a una tabella Iceberg

Se si dispone già di una tabella Iceberg in una posizione di archiviazione supportata dai collegamenti OneLake, seguire questa procedura per creare un collegamento e far apparire la tabella Iceberg con il formato Delta Lake.

1. Trova la tabella Iceberg. Trovare la posizione in cui è archiviata la tabella Iceberg, che potrebbe trovarsi in Azure Data Lake Storage, OneLake, Amazon S3, Google Cloud Storage o in un servizio di archiviazione compatibile con S3.

   Nota

   Se si usa Snowflake e non si è certi della posizione in cui è archiviata la tabella Iceberg, è possibile eseguire l'istruzione seguente per visualizzare la posizione di archiviazione della tabella Iceberg.

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

   L'esecuzione di questa istruzione restituisce un percorso al file di metadati per la tabella Iceberg. Questo percorso indica quale account di archiviazione contiene la tabella Iceberg. Ecco ad esempio le informazioni pertinenti per trovare il percorso di una tabella Iceberg archiviata in 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"}

   La cartella della tabella Iceberg deve contenere una metadata cartella, che contiene almeno un file che termina con .metadata.json.

2. Nel Fabric Lakehouse, crea un nuovo collegamento a tabella nell'area Tabelle di un Lakehouse.

   Suggerimento

   Se vengono visualizzati schemi come dbo nella cartella Tabelle del lakehouse, allora il lakehouse è dotato di schema. In questo caso, fare clic con il pulsante destro del mouse sullo schema e creare un collegamento alla tabella sotto lo schema.

   

3. Per il percorso di destinazione del collegamento, selezionare la cartella delle tabelle Iceberg. La cartella della tabella Iceberg contiene le metadata cartelle e data .

4. Dopo aver creato la scorciatoia, questa tabella dovrebbe essere visualizzata automaticamente come tabella Delta Lake nel data lakehouse, pronta per l'uso in tutto Fabric.

   

   Se il nuovo collegamento alla tabella Iceberg non viene visualizzato come tabella utilizzabile, vedere la sezione Risoluzione dei problemi .

Risoluzione dei problemi

I suggerimenti seguenti consentono di assicurarsi che le tabelle iceberg siano compatibili con questa funzionalità:

Controllare la struttura di cartelle della tabella Iceberg

Aprire la cartella Iceberg nello strumento di esplorazione dello spazio di archiviazione preferito e controllare l'elenco della directory della cartella Iceberg nella posizione originale. Verrà visualizzata una struttura di cartelle simile all'esempio seguente.

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

Se la cartella dei metadati non viene visualizzata o se non vengono visualizzati i file con le estensioni mostrate in questo esempio, potrebbe non essere presente una tabella Iceberg generata correttamente.

Controllare il log di conversione

Quando una tabella Iceberg viene virtualizzata come tabella Delta Lake, è possibile trovare una cartella denominata _delta_log/ all'interno della cartella di collegamento. Questa cartella contiene i metadati del formato Delta Lake (log Delta) dopo la conversione corretta.

Questa cartella include anche il latest_conversion_log.txt file, che contiene i dettagli sull'esito positivo o negativo della conversione tentata più recente.

Per visualizzare il contenuto di questo file dopo aver creato il collegamento, aprire il menu per il collegamento alla tabella Iceberg nell'area Tabelle del lakehouse e selezionare Visualizza file.

Verrà visualizzata una struttura simile all'esempio seguente:

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.

Aprire il file di log della conversione per visualizzare i dettagli dell'ora di conversione o dell'errore più recenti. Se non viene visualizzato un file di log di conversione, la conversione non è stata tentata.

Comprendi il registro delle conversioni e le categorie di errore

Il latest_conversion_log.txt file registra l'ultimo tentativo di conversione. Quando virtualizzi una tabella Iceberg come Delta Lake, trovi questo file nella cartella della _delta_log/ tabella. Quando virtualizzi una tabella Delta Lake come Iceberg, è nella cartella della metadata/ tabella. Il file è in testo semplice. Quando una conversione fallisce, latest_conversion_log.txt contiene un blocco strutturato simile al seguente:

Status:             Failed
Timestamp (UTC):    2025-07-29T19:04:11Z
Latest Metadata:    00000000000000000012.metadata.json
Invocation Id:      6f1c...e2
Root Activity Id:   9a3d...b7
Error Code:         <code>
Error Category:     USER | SYSTEM
Error Details:      <message>

Usa la Categoria Errore per decidere cosa fare dopo:

• USER significa che la tabella sorgente contiene qualcosa che questa funzione non può convertire. Dettagli dell'errore descrive cosa correggere. Regolare la tabella sorgente (vedi Limitazioni e considerazioni), e poi effettuare un commit per una modifica nella tabella sorgente. La conversione si riattiva automaticamente dopo il prossimo commit.

• SYSTEM significa che si è verificato un errore interno o transitorio e non c'è nulla da correggere nella tabella sorgente. Per avviare un altro tentativo di conversione, effettua il commit di una modifica alla tabella sorgente. Se i guasti persistono, contatta il supporto e fornisci l'intero latest_conversion_log.txt file.

Se la conversione non è stata tentata

Se non viene visualizzato un file di log di conversione, la conversione non è stata tentata. Ecco due motivi comuni per cui la conversione non viene tentata:

• Il collegamento non è stato creato nel posto giusto.

  Affinché un collegamento a una tabella Iceberg venga convertito nel formato Delta Lake, il collegamento deve essere posizionato direttamente nella cartella Tables di una lakehouse non abilitata per lo schema. Non è consigliabile posizionare il collegamento nella sezione File o in un'altra cartella se si vuole che la tabella venga virtualizzata automaticamente come tabella Delta Lake.

  

• Il percorso di destinazione del collegamento non è il percorso della cartella Iceberg.

  Quando si crea il collegamento, il percorso della cartella selezionato nel percorso di archiviazione di destinazione deve essere solo la cartella della tabella Iceberg. Questa cartella contiene le metadata cartelle e data .

  

Messaggio di errore "Impossibile convalidare la regione di capacità del tessuto" in Snowflake

Se si usa Snowflake per scrivere una nuova tabella Iceberg in OneLake, è possibile che venga visualizzato il messaggio di errore seguente:

Non è possibile convalidare l'area di capacità dell'infrastruttura. Motivo: "Token di accesso non valido. Ciò può essere dovuto all'autenticazione e alla definizione del perimetro. Si prega di verificare gli ambiti delegati.

Se viene visualizzato questo errore, verificare che l'amministratore del tenant di Fabric abbia abilitato entrambe le impostazioni del tenant indicate nella sezione Scrivere una tabella Iceberg in OneLake usando Snowflake :

1. Nell'angolo superiore destro dell'interfaccia utente di Infrastruttura aprire Impostazioni e selezionare Portale di amministrazione.
2. In Impostazioni tenant, nella sezione Impostazioni sviluppatore, abilitare l'impostazione Entità servizio possono usare le API di Fabric.
3. Nella stessa area, nella sezione Impostazioni di OneLake abilitare l'impostazione Users can access data stored in OneLake with apps external to Fabric (Gli utenti possono accedere ai dati archiviati in OneLake con app esterne a Fabric).

Limitazioni e considerazioni

Tieni presente le seguenti limitazioni quando usi questa funzione. Alcune limitazioni si applicano a entrambe le direzioni di conversione. Altri sono specifici per convertire Delta Lake in Iceberg o Iceberg in Delta Lake.

Come emergono i problemi di conversione

Quando una funzione sorgente non può essere completamente tradotta, succede una di due cose. Entrambi gli esiti sono riportati nel registro delle conversioni.

Limitazioni generali

• Supporto per la versione Apache Iceberg

  La versione supportata dell'Iceberg dipende dalla direzione di conversione:

  Direzione di conversione	Comportamento della versione Iceberg
  Da Delta Lake a Iceberg	Produce i metadati Iceberg V2.
  Da Iceberg a Delta Lake	Supporta le tabelle di origine Iceberg V2. Le tabelle sorgente di Iceberg V3 sono parzialmente supportate; vedi caratteristiche di Iceberg V3.

• Solo file di dati Parquet

  Questa funzione supporta solo Parquet come formato di file dati sottostante per la traduzione dei metadati, in entrambe le direzioni di conversione.

• Versione dei metadati più recente convertita

  La funzionalità di virtualizzazione del formato tabella converte attualmente la versione più recente dei metadati della tabella nel formato di tabella originale. Se più versioni vengono scritte nel formato di tabella originale, solo la versione dei metadati della tabella più recente verrà convertita nel formato di tabella virtuale.

• Numero massimo di transazioni in ingresso

  Le tabelle sorgente devono avere meno di 5.000 transazioni o commit affinché la conversione del formato della tabella avvenga. Assicurati di compattare i log o i manifesti delle transazioni per ridurre il numero di transazioni o commit.

• Latenza di conversione e frequenza di aggiornamento

  La generazione di metadati in formato tabella può richiedere tra 5 secondi e 2 minuti. Assicurati che gli aggiornamenti che apporti alla tabella delle fonti siano meno frequenti di una volta ogni 2 minuti. Altrimenti, potresti vedere una visuale incoerente del formato della tabella di output.

• Evoluzione dello schema

  In entrambe le direzioni di conversione, sono supportate le conversioni a un tipo più ampio (ad esempio, da int a long). Una modifica restrittiva del tipo o comunque incompatibile fa fallire la conversione.

Da Delta Lake a Iceberg

Queste limitazioni si applicano quando virtualizzi un tavolo Delta Lake come Iceberg.

Si applicano le seguenti considerazioni, specialmente per le tabelle di Delta Lake che non sono scritte con una IcebergCompat funzione di scrittura:

• Le colonne annidate array e map richiedono ID di campo stabili per i relativi elemento, chiave e valore. Senza di essi, la colonna di raccolta annidata viene eliminata dall'output dell'iceberg (indicato nel registro di conversione). IcebergCompat assegna questi ID.

• I timestamp devono essere memorizzati come INT64 microsecondi. Una tabella i cui timestamp sono fisicamente memorizzati come INT96 (legacy) si converte, ma le sue colonne timestamp non possono essere lette dai motori Iceberg. IcebergCompat impone timestamp di tipo INT64.

• Ridenominazione delle colonne — Preservata quando la tabella Delta Lake usa la mappatura delle colonne (id o modalità name), come richiesto da IcebergCompat. Con la modalità di mapping delle colonne none, la ridenominazione equivale alla rimozione e all'aggiunta di una colonna.

• Tipi di colonne — Solo i tipi compatibili con Iceberg vengono convertiti; altre colonne vengono eliminate (indicato nel registro di conversione). Ad esempio, void non ha un equivalente di Iceberg. IcebergCompat limita lo schema a un insieme di tipi convertibili.

• Partizionamento — Identità e partizioni temporali (anno, mese, giorno, ora) vengono convertite. Delta Lake ha un unico partizionamento a livello di tabella.

Da Iceberg a Delta Lake

Queste limitazioni si applicano quando virtualizzi una tabella Iceberg come Delta Lake.

• Il cambio di nomi delle colonne non è supportato. Non puoi rinominare una colonna nella tabella Iceberg sorgente. Invece, ricrea la tabella con i nuovi nomi delle colonne. Quando ricrei la tabella, rimuovi eventuali file di metadati residui, come descritto nella tabella Iceberg, le cartelle devono contenere un solo insieme di file di metadati limitati.

• Trasformazioni di partizionamento — Sono supportate solo le trasformazioni di identità e temporali (anno, mese, giorno, ora). Le bucket[N]trasformazioni , truncate[W], e void vengono ignorate: la tabella converte ancora, ma senza tale partizionamento. La colonna sottostante viene preservata come colonna regolare, non partizionale.

• Evoluzione delle partizioni — Se i file dati attivi della tabella sorgente coprono più di una specifica di partizione, o se le colonne di partizione di una tabella precedentemente convertita cambiano, la conversione viene rifiutata. Delta Lake ha una partizionazione unica a livello di tabella, e convertire file a specifiche miste producerebbe in modo errato valori di partizione nulli per i file più vecchi. Mantieni una specifica di partizione singola.

• Cancellazioni a livello di riga — le cancellazioni di posizione Iceberg V2 e i vettori di cancellazione V3 vengono convertite in vettori di cancellazione Delta Lake. Le eliminazioni di uguaglianza causano il fallimento della conversione.

• Tipi non supportati — I tipi senza equivalente Delta Lake (ad esempio, time, e i tipi estesi Iceberg V3) vengono eliminati; uuid vengono mappati in binario. Vedi le caratteristiche dell'Iceberg V3.

• Problema di larghezza del carattere

  Se usi Snowflake per scrivere la tua tabella Iceberg e la tabella contiene tipi INT64di colonne , double, o Decimal con precisione >= 10, la tabella virtuale Delta Lake risultante potrebbe non essere consumabile da tutti i motori Fabric. É possibile visualizzare gli errori seguenti:

  Parquet column cannot be converted in file ... Column: [ColumnA], Expected: decimal(18,4), Found: INT32.
  

  Microsoft sta lavorando a una correzione per questo problema.

  Soluzione alternativa: Se stai usando l'interfaccia di anteprima delle tabelle di Lakehouse e vedi questo problema, puoi risolvere questo errore passando alla vista endpoint di SQL analytics (angolo in alto a destra, seleziona la vista Lakehouse, passa all'endpoint SQL analytics) e da lì visualizzando la tabella. Se quindi si torna alla visualizzazione Lakehouse, l'anteprima della tabella dovrebbe essere visualizzata correttamente.

  Se si esegue un notebook o un processo Spark e si verifica questo problema, è possibile risolvere questo errore impostando la spark.sql.parquet.enableVectorizedReader configurazione di Spark su false. Ecco un esempio di comando PySpark da eseguire in un notebook Spark:

  spark.conf.set("spark.sql.parquet.enableVectorizedReader","false")
  

• L'archiviazione dei metadati della tabella Iceberg non è portabile

  I file di metadati di una tabella Iceberg si riferiscono l'uno all'altro usando riferimenti di percorso assoluti. Se si copia o si sposta il contenuto della cartella di una tabella Iceberg in un'altra posizione senza riscrivere i file di metadati iceberg, la tabella diventa illeggibile dai lettori di Iceberg, inclusa questa funzionalità di OneLake.

  Soluzione alternativa:

  Se è necessario spostare la tabella Iceberg in un'altra posizione per usare questa funzionalità, usare lo strumento che originariamente ha scritto la tabella Iceberg per scrivere una nuova tabella Iceberg nella posizione desiderata.

• Le cartelle delle tabelle iceberg devono contenere un solo set di file di metadati

  Se si rilascia e si ricrea una tabella Iceberg in Snowflake, i file di metadati non vengono puliti. Questo comportamento è intenzionale, a supporto della funzionalità di UNDROP in Snowflake. Tuttavia, poiché il collegamento punta direttamente a una cartella e tale cartella include ora più set di file di metadati, non è possibile convertire la tabella finché non si rimuovono i file di metadati della tabella precedente.

  La conversione avrà esito negativo se nella cartella dei metadati della tabella Iceberg vengono trovati più file di metadati.

  Soluzione alternativa:

  Per garantire che la tabella convertita rifletta la versione corretta della tabella:

  • Assicurarsi di non archiviare più tabelle Iceberg nella stessa cartella.
  • Pulire qualsiasi contenuto di una cartella di tabella Iceberg dopo averlo rimosso, prima di ricreare la tabella.

• Modifiche ai metadati non immediatamente visibili

  Se apporti modifiche ai metadati alla tua tabella Iceberg, come aggiungere una colonna, eliminarla, rinominare una colonna o cambiare il tipo di colonna, la tabella potrebbe non essere riconvertita finché non viene effettuata una modifica ai dati, come aggiungere una riga di dati.

  Si sta lavorando a una correzione che seleziona il file di metadati più recente corretto che include la modifica dei metadati più recente.

  Soluzione alternativa:

  Dopo aver apportato la modifica dello schema alla tabella Iceberg, aggiungere una riga di dati o apportare altre modifiche ai dati. Dopo questa modifica, dovrebbe essere possibile aggiornare e visualizzare la visualizzazione più recente della tabella in Fabric.

Caratteristiche dell'Iceberg V3

Questa funzione produce e legge i metadati di Iceberg V2; non scrive i metadati di Iceberg V3. Quando la sorgente è una tabella Iceberg V3, le sue caratteristiche vengono tradotte come descritto nella tabella seguente. Le colonne eliminate e altre note di traduzione sono registrate nel registro di conversione.

Tipi di dati supportati

La tabella seguente mostra come i tipi di dati delle colonne si mappano tra i formati. Salvo indicazione, un tipo viene convertito in entrambe le direzioni.

Per le tabelle Iceberg scritte da Snowflake, anche le colonne long, double o decimal di grandi dimensioni possono essere interessate dal problema relativo alla larghezza del tipo descritto nella sezione da Iceberg a Delta Lake.

Trasformazioni di partizione supportate

Evoluzione dello schema e delle partizioni

Eliminazioni a livello di riga

Quando virtualizzi un tavolo Iceberg come Delta Lake:

Quando virtualizzi un tavolo Delta Lake come Iceberg:

Disponibilità e limitazioni della piattaforma

• Limitazione della disponibilità dell'area

  La funzionalità non è ancora disponibile nelle aree seguenti:

  • Qatar centrale
  • Norvegia occidentale

  Soluzione alternativa:

  Gli spazi di lavoro collegati alle capacità di Fabric in altre regioni possono usare questa funzionalità. Vedere l'elenco completo delle aree in cui è disponibile Fabric.

• Collegamenti privati non supportati

  Questa funzionalità non è attualmente supportata per tenant o aree di lavoro con collegamenti privati abilitati.

  Stiamo lavorando a un miglioramento per rimuovere questa limitazione.

• I tasti di scelta rapida oneLake devono essere della stessa area

  Esiste una limitazione temporanea sull'uso di questa funzionalità con collegamenti che puntano alle posizioni di OneLake: la posizione di destinazione del collegamento deve trovarsi nella stessa area del collegamento stesso.

  Microsoft sta lavorando a un miglioramento per rimuovere questo requisito.

  Soluzione alternativa:

  Se si dispone di un collegamento OneLake a una tabella Iceberg in un'altra lakehouse, assicurarsi che l'altra lakehouse sia associata a una capacità nella stessa regione.

Contenuto correlato

• Usare Snowflake per scrivere o leggere tabelle Iceberg in OneLake.
• Per saperne di più sulle scorciatoie di OneLake.