Leggere le tabelle Delta Lake con i client Iceberg usando UniForm

Disponibile in Databricks Runtime 14.3 LTS e versioni successive, le letture di Iceberg consentono di configurare le tabelle Delta Lake per generare automaticamente metadati Iceberg, consentendo ai client Iceberg di leggere i dati Delta Lake senza riscrivere i file.

È possibile configurare una connessione esterna per fare in modo che Unity Catalog funga da catalogo Iceberg. Vedere Accedere alle tabelle di Azure Databricks dai client Apache Iceberg.

Come funzionano le operazioni di lettura di Iceberg

Sia Delta Lake che Apache Iceberg sono costituiti da file di dati Parquet e da un livello di metadati. L'abilitazione delle letture di Iceberg configura le tabelle Delta Lake per generare automaticamente metadati Iceberg in modo asincrono, senza riscrivere i dati, consentendo ai client Iceberg di leggerli. Una singola copia dei file di dati supporta più formati.

Quando si utilizzano le operazioni di lettura di Iceberg, considerare quanto segue:

• Le tabelle Delta Lake con le letture Iceberg abilitate usano Zstandard anziché Snappy come codec di compressione per i file di dati Parquet sottostanti.
• La generazione dei metadati Iceberg viene eseguita in modo asincrono sulle risorse di calcolo utilizzate per scrivere dati nelle tabelle Delta Lake, il che potrebbe aumentare l'utilizzo delle risorse del driver.

Per la documentazione sulla funzionalità di tabella UniForm IcebergCompatV1 legacy, vedere Legacy UniForm IcebergCompatV1.

Requisiti

Per abilitare le letture di Iceberg, è necessario soddisfare i requisiti seguenti:

• La tabella Delta Lake deve essere registrata in Unity Catalog. Sono supportate sia tabelle gestite che esterne.
• Per la tabella deve essere abilitato il mapping delle colonne. Vedi Rinominare ed eliminare colonne con la mappatura delle colonne di Delta Lake.
  • Dopo aver abilitato IcebergCompatV2 per una tabella, non è possibile rimuovere la funzionalità di tabella columnMapping.
• La tabella Delta Lake deve avere un valore minReaderVersion>= 2 e minWriterVersion>= 7. Vedere Compatibilità e protocolli delle funzionalità delta Lake.
• Le scritture nella tabella devono usare Databricks Runtime 14.3 LTS o versione successiva.

Abilitare le letture di Iceberg (UniForm)

Quando si abilitano le letture di Iceberg per la prima volta, inizia la generazione di metadati asincroni. Questa attività deve essere completata prima che i client esterni possano eseguire query sulla tabella usando Iceberg. Vedere Controllare lo stato di generazione dei metadati di Iceberg.

Per un elenco delle limitazioni, vedere Limitazioni.

Durante la creazione della tabella

La mappatura delle colonne si abilita automaticamente quando si abilita la lettura di Iceberg durante la creazione della tabella:

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

Databricks consiglia di impostare delta.columnMapping.mode = id per scopi di compatibilità. Vedi Rinominare ed eliminare colonne con la mappatura delle colonne di Delta Lake.

In una tabella esistente

Per abilitare la lettura di Iceberg su una tabella esistente in Databricks Runtime 15.4 LTS o versioni successive:

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

Per informazioni dettagliate sulla modalità di mapping delle name colonne, vedere Modalità di mapping delle colonne.

Abilitare o aggiornare il supporto per la lettura di Iceberg tramite REORG

Usare REORG per abilitare le letture di Iceberg se una delle condizioni seguenti è vera:

• Hai abilitato i vettori di eliminazione sulla tua tabella.
• In precedenza avevi abilitato la versione IcebergCompatV1 di UniForm Iceberg.
• È necessario leggere dai motori Iceberg che non supportano file Parquet in stile Hive, ad esempio Athena o Redshift.

Per abilitare le letture di Iceberg e riscrivere i file di dati sottostanti, usare REORG come nell'esempio seguente:

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

Verificare che le letture di Iceberg siano abilitate

Usare DESCRIBE EXTENDED per verificare che le letture di Iceberg (UniForm) siano abilitate per la tabella:

DESCRIBE EXTENDED catalog_name.schema_name.table_name;

Cercare la sezione Delta Uniform Iceberg nell'output. Se questa sezione è presente, le letture di Iceberg sono abilitate nella tabella.

In alternativa, è possibile usare SHOW TBLPROPERTIES:

SHOW TBLPROPERTIES catalog_name.schema_name.table_name;

Verificare le proprietà seguenti:

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

Se entrambe le proprietà sono presenti con questi valori, le letture di Iceberg sono abilitate.

Disattivare la lettura di Iceberg

È possibile disattivare le letture di Iceberg annullando l'impostazione della delta.universalFormat.enabledFormats proprietà della tabella:

ALTER TABLE table_name UNSET TBLPROPERTIES ('delta.universalFormat.enabledFormats');

Non è possibile annullare gli aggiornamenti alle versioni del protocollo di lettura e scrittura Delta Lake. Vedere Compatibilità e protocolli delle funzionalità delta Lake.

Generazione dei metadati di Iceberg

Azure Databricks attiva la generazione asincrona dei metadati dopo il completamento di una transazione di scrittura Delta Lake. Questo processo di generazione dei metadati usa lo stesso calcolo che ha completato la transazione Delta Lake.

È anche possibile attivare manualmente la generazione di metadati Iceberg. Vedere Attivare manualmente la conversione dei metadati di Iceberg.

Per evitare le latenze di scrittura associate alla generazione dei metadati, le tabelle Delta Lake con commit frequenti possono raggruppare più commit Delta Lake in un unico commit dei metadati Iceberg.

Delta Lake garantisce che un solo processo di generazione di metadati sia in corso su una determinata risorsa di calcolo. I commit che attivano un secondo processo di generazione di metadati simultanei eseguono correttamente il commit in Delta Lake, ma non attivano la generazione asincrona di metadati Iceberg. In questo modo si evita la latenza a catena per la generazione di metadati per i carichi di lavoro con commit frequenti (da secondi a minuti tra i commit).

Vedere Versioni delle tabelle Delta e Iceberg.

Versioni delle tabelle Delta ed Iceberg

Delta Lake e Iceberg consentono query di spostamento del tempo usando le versioni delle tabelle o i timestamp archiviati nei metadati della tabella.

Non è garantito che le versioni delle tabelle Delta Lake siano allineate con le versioni di Iceberg né in base al timestamp del commit né all'ID della versione. Per verificare la versione di una tabella Delta Lake a cui corrisponde una determinata versione di una tabella Iceberg, utilizzare le proprietà della tabella corrispondenti. Vedere Controllare lo stato di generazione dei metadati di Iceberg.

Controllare lo stato di generazione dei metadati di Iceberg

L'abilitazione delle letture di Iceberg in una tabella aggiunge i campi seguenti ai metadati della tabella Di Unity Catalog e Iceberg per tenere traccia dello stato di generazione dei metadati:

In Azure Databricks è possibile esaminare questi campi di metadati eseguendo una delle operazioni seguenti:

• Revisione della sezione Delta Uniform Iceberg restituita da DESCRIBE EXTENDED table_name.
• Revisione dei metadati della tabella con Esplora cataloghi.

Vedere la documentazione per il client lettore Iceberg per informazioni su come esaminare le proprietà delle tabelle all'esterno di Azure Databricks. Per OSS Apache Spark, è possibile visualizzare queste proprietà usando la sintassi seguente:

SHOW TBLPROPERTIES <table-name>;

Attivare manualmente la conversione dei metadati Iceberg

È possibile attivare manualmente la generazione dei metadati Iceberg per la versione più recente della tabella Delta Lake. Questa operazione viene eseguita in modo sincrono. Al termine, il contenuto del sommario disponibile in Iceberg riflette la versione più recente della tabella Delta Lake disponibile all'avvio del processo di conversione.

Questa operazione non è necessaria in condizioni normali. Usalo per ripristinare nei seguenti casi:

• Un cluster termina prima che la generazione automatica dei metadati abbia esito positivo.
• Un errore o un errore del processo interrompe la generazione dei metadati.
• Un client che non supporta la generazione di metadati UniForm Iceberg scrive nella tabella Delta Lake.

Usare la sintassi seguente per attivare manualmente la generazione di metadati Iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Vedi REPAIR TABLE.

Leggere Iceberg usando un percorso JSON di metadati

Alcuni client di Iceberg, ad esempio BigQuery, richiedono di specificare il percorso dei file di metadati versionati per registrare tabelle Iceberg esterne. Ogni volta che Azure Databricks converte una nuova versione della tabella Delta Lake in Iceberg, crea un nuovo file JSON di metadati.

Per informazioni dettagliate sulla configurazione, vedere la documentazione relativa al client lettore Iceberg specifico.

Delta Lake archivia i metadati di Iceberg nella directory della tabella usando il modello seguente:

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

In Azure Databricks è possibile esaminare questa posizione dei metadati eseguendo una delle operazioni seguenti:

• Revisione della sezione Delta Uniform Iceberg restituita da DESCRIBE EXTENDED table_name.
• Revisione dei metadati della tabella con Esplora cataloghi.

Limitazioni

Esistono le limitazioni seguenti per tutte le tabelle con le letture Iceberg abilitate:

• Il supporto client di Iceberg è di sola lettura. Le operazioni di scrittura non sono supportate.
  • I lettori Iceberg potrebbero avere limitazioni individuali, indipendentemente dal supporto di Azure Databricks per le letture Iceberg. Consultare la documentazione per il cliente scelto.
• I vettori di eliminazione non sono supportati per le letture di Iceberg v2. Apache Iceberg v3 supporta tuttavia vettori di eliminazione. Vedere Usare le funzionalità di Apache Iceberg v3 e i vettori di eliminazione in Databricks.
• Le letture di Iceberg non possono essere abilitate nelle viste materializzate o nelle tabelle di streaming.
• È necessario accedere alla tabella Delta Lake in base al nome (non al percorso) per attivare automaticamente la generazione di metadati Iceberg.
• Le tabelle Delta Lake con la lettura Iceberg abilitata non supportano i tipi VOID.
• Alcune funzionalità della tabella Delta Lake usate dalle letture Iceberg non sono supportate da alcuni client OpenSharing per la lettura. Vedere Che cos'è OpenSharing?.
• I destinatari di OpenSharing possono leggere le tabelle Delta Lake con la lettura Iceberg abilitata come tabelle Iceberg utilizzando l'API REST del catalogo Iceberg. Questa funzionalità è in Anteprima Pubblica. Vedere Abilitare la condivisione ai client Iceberg esterni.
• Il feed dei dati di modifica legacy funziona per i client Delta quando le letture Iceberg sono abilitate, ma non è supportato in Iceberg. Vedere Feed di dati delle modifiche legacy per Delta Lake.