Utilizzare i vettori di eliminazione binaria nelle tabelle Iceberg V3

I vettori di eliminazione binari nelle tabelle Apache Iceberg V3 consentono di registrare le eliminazioni a livello di riga nei file .puffin senza riscrivere interi file di dati. Anziché eseguire join costosi in fase di query, motori come BigQuery, Managed Service for Apache Spark, Apache Flink e Trino utilizzano questi vettori per identificare e saltare le righe eliminate durante le letture.

Supportata nel catalogo di runtime Lakehouse, questa ottimizzazione può migliorare le prestazioni di scrittura e lettura per le pipeline Change Data Capture (CDC) ad alto volume. Inoltre, ti aiuta a soddisfare i requisiti normativi come il GDPR (diritto all'oblio) eliminando i singoli record senza l'overhead della riscrittura dei file di dati.

Prima di iniziare

  1. Verifica che la fatturazione sia attivata per il tuo progetto Google Cloud .

  2. Abilita l'API BigLake, se non è già abilitata.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se hai creato il progetto, probabilmente hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare e gestire le tabelle Iceberg V3, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto e sul bucket di archiviazione:

  • Crea e gestisci le tabelle Iceberg V3:
    • BigLake Admin (roles/biglake.admin) - il tuo progetto
    • Amministratore Storage (roles/storage.admin): il bucket Cloud Storage di destinazione

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura il catalogo REST Iceberg

Prima di creare una tabella Iceberg V3, devi configurare il catalogo REST Iceberg, che include la creazione di uno spazio dei nomi e di un catalogo.

La configurazione del catalogo REST Iceberg può richiedere un po' di tempo. Assicurati di creare correttamente sia lo spazio dei nomi sia il catalogo prima di continuare.

Limitazioni

Le tabelle Iceberg V3 nel catalogo di runtime Lakehouse presentano le seguenti limitazioni:

  • Nuovi tipi di dati V3: i nuovi tipi di dati Iceberg V3 (come Variant, Geography, timestamp in nanosecondi, valori predefiniti e tipi di dati sconosciuti) non sono supportati.
  • Monitoraggio della derivazione delle righe: il monitoraggio della derivazione delle righe non è supportato.
  • Scritture BigQuery: le scritture BigQuery non sono supportate con le tabelle V3. Puoi solo leggere le tabelle V3 da BigQuery. Per creare e scrivere in tabelle V3, devi utilizzare motori open source (come Apache Spark, Apache Flink o Trino).

Requisiti del motore

Assicurati di utilizzare una versione del motore che supporti Iceberg V3 e i vettori di eliminazione binari. È consigliato Apache Spark 3.5 o versioni successive. Gli esempi in questa guida utilizzano iceberg-spark-runtime-3.5_2.12:1.10.1.

Quando configuri la sessione della tabella e del motore, assicurati di quanto segue:

  • Versione formato tabella:deve essere impostata su format-version='3'.
  • Modalità di eliminazione: deve essere impostata su merge-on-read. Questa modalità garantisce che le eliminazioni vengano scritte in file separati (i vettori di eliminazione) anziché riscrivere i file di dati originali (copy-on-write).

Esempio di configurazione di una sessione Spark

La seguente configurazione abilita le estensioni Iceberg necessarie e configura la connessione al catalogo REST:

spark-sql \
    --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.10.1,org.apache.iceberg:iceberg-gcp:1.10.1 \
    --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-gcp-bundle/1.10.1/iceberg-gcp-bundle-1.10.1.jar \
    --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
    --conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
    --conf spark.sql.catalog.CATALOG_NAME.type=rest \
    --conf spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog \
    --conf spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH \
    --conf spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID \
    --conf spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager \
    --conf spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO \
    --conf spark.sql.defaultCatalog=CATALOG_NAME

Sostituisci quanto segue:

  • CATALOG_NAME: il nome dell'endpoint del catalogo REST Apache Iceberg.
  • WAREHOUSE_PATH: l'URI della cartella Cloud Storage in cui è archiviato il tuo data warehouse, che inizia con gs://.
  • PROJECT_ID: il tuo ID progetto Google Cloud .

Utilizza i vettori di eliminazione binari

Per utilizzare i vettori di eliminazione binari nelle tabelle Apache Iceberg V3, devi creare una tabella con la versione di formattazione 3, compilarla con i dati, eseguire le modifiche standard del database ed eseguire query sulla tabella. Puoi eseguire tutte le istruzioni di creazione, inserimento, eliminazione e aggiornamento utilizzando Spark SQL.

Crea una tabella Iceberg con vettori di eliminazione binari

Crea una tabella specificando format-version='3' e le modalità di eliminazione, aggiornamento e unione merge-on-read nelle proprietà della tabella. Esegui la seguente istruzione in Spark SQL:

Spark 

CREATE NAMESPACE IF NOT EXISTS my_namespace;
USE my_namespace;

CREATE TABLE my_namespace.mytable_v3 (
   id BIGINT,
   city STRING,
   state STRING
) TBLPROPERTIES (
   'format-version'='3',
   'write.delete.mode'='merge-on-read',
   'write.update.mode'='merge-on-read',
   'write.merge.mode'='merge-on-read'
);

Esegui l'upgrade di una tabella Iceberg V2 alla versione V3

Puoi eseguire l'upgrade di una tabella Iceberg V2 esistente alla versione V3 utilizzando le istruzioni ALTER TABLE. Il downgrade di una tabella dalla versione V3 alla versione V2 non è supportato. Esegui la seguente istruzione in Spark SQL:

Spark 

ALTER TABLE my_namespace.mytable_v2 SET TBLPROPERTIES ('format-version' = '3');

Inserisci i dati nella tabella

Per garantire che i file dei vettori di eliminazione binari vengano generati per le eliminazioni, il motore non deve eseguire il fallback al copy-on-write. In genere, ciò richiede la presenza di una quantità significativa di dati nella tabella prima dell'operazione di eliminazione. Ad esempio, Apache Spark potrebbe ottimizzare le eliminazioni di piccole dimensioni ricorrendo al copy-on-write. Compila la tabella eseguendo le seguenti istruzioni in Spark SQL:

Spark 

-- Create a temporary view with a large number of rows (100,000 rows)
CREATE OR REPLACE TEMPORARY VIEW large_source AS
SELECT
  id,
  CAST(id AS STRING) as city,
  'WA' as state
FROM (
  SELECT row_number() OVER (ORDER BY (SELECT NULL)) as id
  FROM (SELECT 0 FROM range(1000)) a
  CROSS JOIN (SELECT 0 FROM range(100)) b
);

-- Overwrite the existing table with the generated data
INSERT OVERWRITE my_namespace.mytable_v3 SELECT * FROM large_source;

Elimina dati

Esegui un'istruzione DELETE in Spark SQL. Poiché la tabella è configurata per merge-on-read e dispone di dati sufficienti, Spark genera file di eliminazione utilizzando vettori di eliminazione binari.

Spark 

DELETE FROM my_namespace.mytable_v3 WHERE id = 5000;

Aggiorna i dati

Esegui un'istruzione UPDATE in Spark SQL. Poiché la tabella è configurata per merge-on-read e dispone di dati sufficienti, Spark genera file di eliminazione utilizzando vettori di eliminazione binari.

Spark 

UPDATE my_namespace.mytable_v3 SET state = 'NY' WHERE id = 1;

esegui una query sulla tabella

Le query sulla tabella utilizzano automaticamente i file binari del vettore di eliminazione per escludere le righe eliminate. Puoi eseguire query sulla tabella utilizzando Apache Spark o BigQuery.

Spark 

-- Should be less than the initial 100,000 rows
SELECT count(*) FROM my_namespace.mytable_v3;

-- Should return no results
SELECT * FROM my_namespace.mytable_v3 WHERE id = 5000;

-- Should return 'NY'
SELECT * FROM my_namespace.mytable_v3 WHERE id = 1;

BigQuery

Quando esegui query da BigQuery, utilizza l'identificatore della tabella completo PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3.

bq query --nouse_legacy_sql \
    'SELECT * FROM `PROJECT_ID.CATALOG_NAME.my_namespace.mytable_v3` LIMIT 10'

Verifica la creazione dei vettori di eliminazione binari

Puoi verificare che i vettori di eliminazione binari siano stati creati correttamente esaminando la directory di archiviazione e i metadati degli snapshot.

Controlla se sono presenti file .puffin

Vai alla directory di dati della tabella nel tuo warehouse Cloud Storage (ad esempio gs://WAREHOUSE_BUCKET/my_namespace/mytable_v3/data). Dovresti trovare i file .puffin, che memorizzano i vettori di eliminazione binari.

Esamina i metadati degli snapshot

I metadati dello snapshot nei file JSON della tabella Iceberg contengono informazioni sull'operazione di eliminazione. Cerca proprietà come added-delete-files, added-dvs e operation nel riepilogo dello snapshot. Ciò conferma che sono stati aggiunti i file di eliminazione.

"summary": {
  "operation": "delete",
  "added-delete-files": "1",
  "added-dvs": "1",
  "added-files-size": "42",
  "added-position-deletes": "1",
  ...
}

Passaggi successivi