Condividi tramite

Legacy UniForm IcebergCompatV1

  • Articolo

Importante

Questa documentazione è stata ritirata e potrebbe non essere aggiornata. Il prodotto, il servizio o la tecnologia citati in questo contenuto non sono più supportati. Vedere Usare UniForm per leggere le tabelle Delta con i client Iceberg.

Importante

Questa funzionalità è disponibile in anteprima pubblica in Databricks Runtime 13.2 e versioni successive.

Delta Universal Format (UniForm) consente di leggere le tabelle Delta con client di lettura Iceberg.

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 il catalogo Unity funga da catalogo Iceberg. Consultare Leggere l'endpoint del catalogo Iceberg del catalogo Unity.

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 seguenti requisiti:

Abilitare Delta UniForm

Importante

L'abilitazione di Delta UniForm imposta la funzionalità IcebergCompatV1 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 13.2 o superiore.

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

La proprietà della seguente tabella abilita il supporto UniForm per Iceberg. iceberg è l'unico valore valido.

'delta.universalFormat.enabledFormats' = 'iceberg'

È anche necessario abilitare il mapping delle colonne e IcebergCompatV1 per usare UniForm. Questi vengono impostati automaticamente se si abilita UniForm durante la creazione della tabella, come nel seguente esempio:

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

Se si crea una nuova tabella con un'istruzione CTAS, è necessario specificare manualmente il mapping delle colonne, come nel seguente esempio:

CREATE TABLE T
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.universalFormat.enabledFormats' = 'iceberg')
AS
  SELECT * FROM source_table;

Se si modifica una tabella esistente, è necessario specificare tutte queste proprietà, come nel seguente esempio:

ALTER TABLE T SET TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableIcebergCompatV1' = '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. Consultare Controllare lo stato di generazione dei metadati di Iceberg.

Nota

Se si prevede di usare BigQuery come client lettore Iceberg, è necessario impostare spark.databricks.delta.write.dataFilesToSubdir su true 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 di metadati Iceberg in modo asincrono dopo il completamento di una transazione di scrittura Delta Lake utilizzando lo stesso calcolo che ha completato la transazione Delta. È anche possibile attivare manualmente la generazione di metadati Iceberg. Consultare Attivare manualmente la conversione dei metadati di Iceberg.

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

Delta Lake assicura che in qualsiasi momento sia in corso un solo processo di generazione di metadati Iceberg. 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).

Consultare Versioni delle tabelle Delta e 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 usando Esplora cataloghi. Questi campi e valori vengono restituiti anche quando si usa l'API REST per ottenere una tabella.

Per informazioni su come esaminare le proprietà delle tabelle all'esterno di Azure Databricks, consultare la documentazione per il client lettore 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 di fornire 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

È possibile trovare il percorso di questo file utilizzando Esplora cataloghi. Per le tabelle con UniForm abilitato, i dettagli della tabella Delta includono un campo per la posizione dei metadati Iceberg.

È inoltre possibile utilizzare l'API REST per ottenere tutti i dettagli di una tabella, compresa la posizione dei metadati. Usare il comando seguente:

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. È necessario configurare l'accesso all'archivio oggetti cloud sottostante contenente la tabella Delta con UniForm abilitato. Per informazioni dettagliate sulla configurazione, consultare 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 al catalogo Unity. Consultare Autenticare l'accesso alle risorse di Azure Databricks.

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 nel catalogo Unity usando questo metodo, gli identificatori di oggetto usano il seguente modello:

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

Questo schema utilizza la stessa spaziatura dei nomi a tre livelli presente nel catalogo Unity, ma aggiunge un ulteriore prefisso unity.

Versioni delle tabelle Delta e 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à della tabella corrispondente impostate sulla tabella Iceberg. Consultare Controllare lo stato di generazione dei metadati di Iceberg.

Limiti

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 LIST, MAP e 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. Consultare la documentazione per il client scelto.
  • I client di lettura Iceberg versione 1.2.0 e versioni successive non supportano il tipo INT96 di timestamp scritto da Apache Spark. Utilizzare il seguente codice nei notebook che scrivono in tabelle UniForm per evitare questa limitazione: spark.conf.set(“spark.sql.parquet.outputTimestampType”, “TIMESTAMP_MICROS”)
  • La versione di anteprima pubblica dell'endpoint Iceberg del catalogo Unity non è destinata a carichi di lavoro di produzione su larga scala. È possibile che si verifichi una limitazione della frequenza se si supera una soglia di 5 query al secondo.

Le seguenti funzionalità Delta Lake funzionano per i client Delta quando UniForm è abilitato, ma non sono supportate in Iceberg:

  • Modificare feed di dati
  • Delta Sharing