Usare UniForm per leggere le tabelle Delta con i client Iceberg

  • Articolo

Delta Universal Format (UniForm) consente di leggere le tabelle Delta con client di lettura Iceberg. Questa funzionalità richiede Databricks Runtime 14.3 LTS o versione successiva.

Importante

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

UniForm sfrutta il fatto che sia Delta Lake che Iceberg sono costituiti da file di dati Parquet e da un livello di metadati. UniForm genera automaticamente metadati Iceberg in modo asincrono, senza riscrivere i dati, in modo che i client Iceberg possano leggere le tabelle Delta come se fossero tabelle Iceberg. Una singola copia dei file di dati serve entrambi i formati.

È possibile configurare una connessione esterna per fare in modo che Unity Catalog funga da catalogo Iceberg. Vedere Leggere l'endpoint del catalogo Iceberg del catalogo Unity.

UniForm usa zstd anziché snappy come codec di compressione per i file di dati Parquet sottostanti.

Nota

La generazione di metadati UniForm viene eseguita in modo asincrono nel calcolo usato per scrivere dati in tabelle Delta, che potrebbero aumentare l'utilizzo delle risorse del driver.

Requisiti

Per abilitare UniForm, è necessario soddisfare i requisiti seguenti:

Nota

Non è possibile abilitare i vettori di eliminazione in una tabella con UniForm abilitato. Quando si abilita UniForm in una tabella esistente con vettori di eliminazione abilitati, UniForm disabilita e elimina i vettori di eliminazione e riscrive i file di dati in base alle esigenze.

Abilitare Delta UniForm

Importante

L'abilitazione di Delta UniForm imposta la funzionalità IcebergCompatV2tabella Delta , una funzionalità di protocollo di scrittura. Solo i client che supportano questa funzionalità di tabella possono scrivere in tabelle abilitate per UniForm. È necessario usare Databricks Runtime 14.3 LTS o versione successiva per scrivere nelle tabelle Delta con questa funzionalità abilitata.

È possibile disattivare UniForm annullando l'impostazione della delta.universalFormat.enabledFormats proprietà della tabella. Non è possibile disattivare il mapping delle colonne dopo l'abilitazione e non è possibile annullare l'aggiornamento alle versioni del protocollo di lettura e scrittura Delta Lake.

È necessario impostare le proprietà della tabella seguenti per abilitare il supporto UniForm per Iceberg:

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

È anche necessario abilitare il mapping delle colonne per usare UniForm. Questa opzione viene abilitata automaticamente se si abilita UniForm durante la creazione della tabella, come nell'esempio seguente:

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

È possibile abilitare UniForm in una tabella esistente usando la sintassi seguente:

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

Nota

Questa sintassi funziona anche per eseguire l'aggiornamento dalla versione di anteprima pubblica di UniForm, che ha usato la funzionalità IcebergCompatV1tabella .

Questa sintassi disabilita e elimina automaticamente i vettori di eliminazione dalla tabella. I file esistenti vengono riscritti in base alle esigenze per renderli compatibili con Iceberg.

Quando si abilita uniForm 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.

Nota

Se si prevede di usare BigQuery come client lettore Iceberg, è necessario impostare su spark.databricks.delta.write.dataFilesToSubdirtrue in Azure Databricks per soddisfare un requisito BigQuery per il layout dei dati.

Vedere Limitazioni.

Quando uniForm genera metadati Iceberg?

Azure Databricks attiva la generazione asincrona di metadati Iceberg dopo il completamento di una transazione di scrittura Delta Lake usando lo stesso calcolo che ha completato la transazione Delta. È anche possibile attivare manualmente la generazione di metadati Iceberg. Vedere Attivare manualmente la conversione dei metadati di Iceberg.

Per evitare latenze di scrittura associate alla generazione di metadati Iceberg, le tabelle Delta con commit frequenti potrebbero aggregare più commit Delta in un singolo commit Iceberg.

Delta Lake garantisce che sia in corso un solo processo di generazione dei metadati Iceberg in qualsiasi momento. I commit che attiverebbero un secondo processo di generazione di metadati Iceberg simultanei eseguiranno correttamente il commit in Delta, ma non attiveranno la generazione asincrona dei 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.

Controllare lo stato di generazione dei metadati di Iceberg

UniForm aggiunge i campi seguenti ai metadati della tabella di Unity Catalog e Iceberg per tenere traccia dello stato di generazione dei metadati:

Campo dei metadati Descrizione
converted_delta_version Versione più recente della tabella Delta per la quale sono stati generati correttamente i metadati di Iceberg.
converted_delta_timestamp Timestamp dell'ultimo commit Delta per il quale sono stati generati correttamente i metadati di Iceberg.

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

  • Revisione della Delta Uniform Iceberg sezione restituita da DESCRIBE EXTENDED table_name.
  • Revisione dei metadati della tabella con Esplora cataloghi.
  • Uso dell'API REST per ottenere una tabella.

Per informazioni su come esaminare le proprietà delle tabelle all'esterno di Azure Databricks, vedere la documentazione per il client lettore Iceberg. 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. Questa operazione viene eseguita in modo sincrono, ovvero quando viene completata, il contenuto del sommario disponibile in Iceberg riflette la versione più recente della tabella Delta disponibile all'avvio del processo di conversione.

Questa operazione non deve essere necessaria in condizioni normali, ma può essere utile se si verificano le operazioni seguenti:

  • 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.
  • Client che non supporta la scrittura di metadati UniForm Iceberg nella tabella Delta.

Usare la sintassi seguente per attivare manualmente la generazione dei metadati iceberg:

MSCK REPAIR TABLE <table-name> SYNC METADATA

Vedere REPAIR TABLE.

Leggere usando un percorso JSON di metadati

Alcuni client Iceberg richiedono di fornire un percorso ai file di metadati con controllo delle versioni per registrare tabelle Iceberg esterne. Ogni volta che UniForm converte una nuova versione della tabella Delta in Iceberg, crea un nuovo file JSON di metadati.

I client che usano i percorsi JSON dei metadati per la configurazione di Iceberg includono BigQuery. Per informazioni dettagliate sulla configurazione, vedere la documentazione relativa al client lettore Iceberg.

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 Delta Uniform Iceberg sezione restituita da DESCRIBE EXTENDED table_name.
  • Revisione dei metadati della tabella con Esplora cataloghi.
  • Usando il comando seguente con l'API REST:
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

La risposta include le informazioni seguenti:

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

Importante

I client di lettura Iceberg basati su percorso potrebbero richiedere l'aggiornamento manuale e l'aggiornamento dei percorsi JSON dei metadati per leggere le versioni correnti della tabella. Gli utenti potrebbero riscontrare errori durante l'esecuzione di query sulle tabelle Iceberg usando versioni non aggiornate quando i file di dati Parquet vengono rimossi dalla tabella Delta con VACUUM.

Leggere usando l'endpoint del catalogo Iceberg del catalogo Unity

Alcuni client Iceberg possono connettersi a un catalogo REST di Iceberg. Il catalogo Unity fornisce un'implementazione di sola lettura dell'API del catalogo REST Iceberg per le tabelle Delta con UniForm abilitato usando l'endpoint /api/2.1/unity-catalog/iceberg. Per informazioni dettagliate sull'uso di questa API REST, vedere la specifica dell'API REST Iceberg.

I client noti per supportare l'API del catalogo Iceberg includono Apache Spark, Flink e Trino. È necessario configurare l'accesso all'archivio oggetti cloud sottostante contenente la tabella Delta con UniForm abilitato. Per informazioni dettagliate sulla configurazione, vedere la documentazione relativa al client lettore Iceberg.

È necessario generare e configurare un token di accesso personale di Azure Databricks per consentire ad altri servizi di connettersi a Unity Catalog. Vedere Autenticazione per l'automazione di Azure Databricks - Panoramica.

Di seguito è riportato un esempio delle impostazioni per configurare OSS Apache Spark per leggere UniForm come 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

Sostituire l'URL completo dell'area di lavoro in cui è stato generato il token di accesso personale per <api-root>.

Nota

Quando si eseguono query su tabelle in Unity Catalog usando questo metodo, gli identificatori di oggetto usano il modello seguente:

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

Questo modello usa gli stessi nomi a tre livelli presenti nel catalogo unity, ma aggiunge un prefisso unityaggiuntivo .

Versioni delle tabelle Delta ed Iceberg

Sia Delta Lake che Iceberg consentono query di spostamento del tempo usando versioni di tabella o timestamp archiviati nei metadati della tabella.

In generale, le versioni della tabella Iceberg e Delta non sono allineate in base al timestamp di commit o all'ID versione. Se si desidera verificare a quale versione di una tabella Delta corrisponde una determinata versione di una tabella Iceberg, è possibile utilizzare le proprietà di tabella corrispondenti impostate sulla tabella Iceberg. Vedere Controllare lo stato di generazione dei metadati di Iceberg.

Limiti

Esistono le limitazioni seguenti:

  • UniForm non funziona nelle tabelle con vettori di eliminazione abilitati. Vedere Che cosa sono i vettori di eliminazione?.
  • Le tabelle Delta con UniForm abilitato non supportano VOID i tipi.
  • I client Iceberg possono leggere solo da UniForm. Le scritture non sono supportate.
  • I client di lettore iceberg potrebbero avere limitazioni individuali, indipendentemente da UniForm. Vedere la documentazione per il client scelto.
  • I destinatari di Delta Sharing possono leggere la tabella solo come Delta, anche quando UniForm è abilitato.

Il feed di dati delle modifiche funziona per i client Delta quando UniForm è abilitato, ma non dispone del supporto in Iceberg.

Alcune funzionalità della tabella Delta Lake usate da UniForm non sono supportate da alcuni client con autorizzazioni di lettura per la condivisione Delta. Vedere Condividere i dati e gli asset di intelligenza artificiale in modo sicuro usando la condivisione Delta.