Condividi tramite

Usare UniForm per leggere le tabelle Delta con i client Iceberg

  • Articolo

Formato Delta Lake Universal (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.

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

UniForm Iceberg usa Zstandard 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.

Come funziona UniForm?

UniForm sfrutta il fatto che Delta Lake e 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. Una singola copia dei file di dati serve più formati.

Requisiti

Per abilitare UniForm Iceberg, è necessario soddisfare i seguenti requisiti:

Nota

Non è possibile abilitare i vettori di eliminazione in una tabella con UniForm Iceberg abilitato.

Usare REORG per disabilitare ed eliminare i vettori di eliminazione durante l'abilitazione di UniForm Iceberg in una tabella esistente con vettori di eliminazione abilitati. Si veda Abilitare o aggiornare con REORG.

Abilitare UniForm Iceberg

Importante

L'abilitazione di Delta UniForm imposta la funzionalità IcebergCompatV2 della tabella Delta, una funzionalità di protocollo di scrittura. Solo i client che supportano questa funzionalità di tabella sono autorizzati scrivere in tabelle abilitate per UniForm. Per scrivere sulle tabelle Delta con questa funzione abilitata, è necessario utilizzare Databricks Runtime 14.3 LTS o superiore.

È possibile disattivare UniForm annullando l'impostazione della proprietà delta.universalFormat.enabledFormats della tabella. Non è possibile annullare gli aggiornamenti alle versioni del protocollo di lettura e scrittura Delta Lake.

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

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

Quando si attiva UniForm per la prima volta, inizia la generazione asincrona dei metadati. Questa attività deve essere completata prima che i client esterni possano eseguire query sulla tabella usando Iceberg. Si veda Controllare lo stato di generazione dei metadati di Iceberg.

Consultare Limitazioni per un elenco delle limitazioni.

Abilitare durante la creazione di tabelle

Per usare UniForm Iceberg, è necessario abilitare il mapping delle colonne. Questo accade automaticamente se si abilita UniForm Iceberg durante la creazione della tabella, come nel seguente esempio:

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

Abilitare modificando una tabella esistente

In Databricks Runtime 15.4 LTS e versioni successive è possibile abilitare o aggiornare UniForm Iceberg in una tabella esistente usando la sintassi seguente:

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

Abilitare o aggiornare tramite REORG

È possibile usare REORG per abilitare UniForm Iceberg e riscrivere i file di dati sottostanti, come nell'esempio seguente:

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

Usare REORG se uno dei seguenti valori è vero:

  • La tabella include vettori di eliminazione abilitati.
  • In precedenza è stata abilitata la versione IcebergCompatV1 di UniForm Iceberg.
  • È necessario leggere dai motori Iceberg che non supportano file Parquet in stile Hive, ad esempio Apache o Redshift.

Quando UniForm genera metadati Iceberg?

Azure Databricks attiva la generazione di metadati in modo asincrono 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.

Nota

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

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

Delta Lake assicura che in qualsiasi momento sia in corso un solo processo di generazione di metadati su una determinata risorsa del computer. I commit che attiverebbero un secondo processo di generazione di metadati simultanei eseguono correttamente il commit in Delta, ma non attivano 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).

Si veda Versioni delle tabelle Delta e Iceberg.

Versioni delle tabelle Delta e Iceberg

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 Delta non sono allineate alle versioni Iceberg in base al timestamp di commit o all'ID versione. Per verificare a quale versione di una tabella Delta corrisponde una determinata versione di una tabella Iceberg, è possibile utilizzare le proprietà della tabella corrispondente. Si veda Controllare lo stato di generazione dei metadati di Iceberg.

Controllare lo stato di generazione dei metadati di Iceberg

UniForm aggiunge i campi seguenti ai metadati della tabella del catalogo Unity 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 Il timestamp dell'ultimo commit Delta per il quale i metadati Iceberg sono stati generati con successo.

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.
  • 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 di lettura Iceberg. Per OSS Apache Spark, è possibile visualizzare queste proprietà usando la seguente sintassi:

SHOW TBLPROPERTIES <table-name>;

Attivare manualmente la conversione dei metadati di Iceberg

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

Questa operazione non dovrebbe essere necessaria in condizioni normali, ma può essere utile se si verificano i seguenti casi:

  • Un cluster termina prima che la generazione automatica dei metadati sia completata correttamente.
  • Un errore o un errore del processo interrompe la generazione dei metadati.
  • Un client che non supporta la scrittura di metadati UniForm Iceberg scrive nella tabella Delta.

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

MSCK REPAIR TABLE <table-name> SYNC METADATA

Si veda Tabella di riparazione.

Leggere usando un percorso JSON di metadati

Alcuni client Iceberg richiedono che tu fornisca un percorso ai file di metadati in versione 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 utilizzano i percorsi JSON dei metadati per configurare Iceberg includono BigQuery. Per informazioni dettagliate sulla configurazione, si veda la documentazione relativa al client di lettura Iceberg.

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

<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.
  • Usare 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 di Iceberg basati sui percorsi potrebbero richiedere l'aggiornamento manuale e la ricarica dei percorsi JSON dei metadati per leggere le versioni correnti delle tabelle. Gli utenti potrebbero riscontrare degli errori quando interrogano le tabelle Iceberg utilizzando versioni non aggiornate, poiché i file di dati Parquet vengono rimossi dalla tabella Delta con VACUUM.

Leggere utilizzando l'endpoint del catalogo Unity Catalog Iceberg

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 con l'endpoint /api/2.1/unity-catalog/iceberg. Per informazioni dettagliate sull'uso di questa API REST, si veda la specifica dell'API REST Iceberg.

I client noti per supportare l'API del catalogo Iceberg includono Apache Spark, Flink e Trino. Per informazioni dettagliate sulla configurazione, si veda la documentazione relativa al client di lettura Iceberg.

Autenticazione e autorizzazione

Esistono due requisiti per l'accesso ai dati registrati in Unity Catalog usando l'endpoint api/2.1/unity-catalog/iceberg da servizi esterni:

Esempio di configurazione Apache Spark:

Di seguito è riportato un esempio delle impostazioni utilizzate per configurare OSS Apache Spark per la lettura di 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.type": "rest",
"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.warehouse": "<uc_catalog_name>"

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

Quando si eseguono query su tabelle in Unity Catalog usando configurazioni Spark, tenere presente quanto segue:

  • Gli identificatori di oggetto usano il criterio unity.<schema-name>.<table-name>.

    Questo criterio usa lo stesso spazio dei nomi a tre livelli usato in Unity Catalog, ma con il nome del catalogo sostituito da unity.

  • È necessario "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" solo se si eseguono stored procedure specifiche di Iceberg.

  • Se si usa un provider di servizi cloud per l'archiviazione, è necessario aggiungere i file JAR del bundle Iceberg specifici del cloud come pacchetti Spark:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    Per informazioni dettagliate, vedere la documentazione relativa all'integrazione di Iceberg AWS per Spark.

Esempio di curl dell'API REST

È anche possibile usare una chiamata API REST come quella in questo esempio di curl per caricare una tabella:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

Si riceverà una risposta come la seguente:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

Nota

Il campo expires-at-ms nella risposta indica l'ora di scadenza delle credenziali e ha una scadenza predefinita di un'ora. Per prestazioni migliori, è necessario che il client memorizzi nella cache le credenziali fino alla scadenza prima di richiederne una nuova.

Limiti

Per tutte le tabelle UniForm esistono le limitazioni seguenti:

  • UniForm non funziona nelle tabelle con vettori di eliminazione abilitati. Si veda Che cosa sono i vettori di eliminazione?.
  • Le tabelle Delta con UniForm abilitato non supportano i tipi VOID.
  • I client Iceberg possono leggere solo da UniForm. Le operazioni di scrittura non sono supportate.
  • I client di lettura iceberg potrebbero avere limitazioni individuali, indipendentemente da UniForm. Si veda la documentazione per il client scelto.
  • I destinatari di Delta Sharing possono leggere la tabella solo come Delta, anche quando UniForm è abilitato.
  • Alcune funzionalità della tabella Delta Lake usate da UniForm Iceberg non sono supportate da alcuni client Delta Sharing con autorizzazioni di lettura. Si veda Che cos'è Delta Sharing?.

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