Utilizzare i vettori di eliminazione binaria nelle tabelle Iceberg V3

Il catalogo runtime Lakehouse supporta le tabelle Apache Iceberg V3. Una caratteristica principale della specifica Apache Iceberg V3 sono i vettori di eliminazione binaria. Questa ottimizzazione archivia le eliminazioni a livello di riga nei file .puffin. Anziché eseguire join costosi al momento della query, BigQuery e i motori open source (come Apache Spark, Apache Flink e Trino) utilizzano questi vettori per identificare e ignorare rapidamente le righe eliminate.

L'utilizzo di vettori di eliminazione binari può migliorare le prestazioni nei seguenti modi:

  • Scritture di volumi elevati:migliora le prestazioni di scrittura per le tabelle con scritture di volumi elevati.
  • Letture efficienti:migliora la velocità delle query consentendo a BigQuery e ai motori open source di identificare e ignorare le righe eliminate.

Ciò è particolarmente utile per gestire aggiornamenti ed eliminazioni di grandi volumi nelle pipeline di Change Data Capture (CDC) o per soddisfare i requisiti normativi come il GDPR (diritto all'oblio) eliminando righe specifiche senza il sovraccarico di riscrittura di interi file di dati.

Prima di iniziare

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

  2. Abilita l'API BigLake.

    Ruoli richiesti per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

    Abilitare l'API

Ruoli obbligatori

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

  • Tutti:
    • 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 Iceberg REST, 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. Prima di continuare, assicurati di creare correttamente sia lo spazio dei nomi sia il catalogo.

Limitazioni

Le tabelle Iceberg V3 nel catalogo 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 leggere solo le tabelle V3 da BigQuery. Per creare tabelle V3 e scriverci, 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 binaria. È consigliabile Apache Spark 3.5 o versioni successive. Gli esempi riportati 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 del formato della 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 della 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 data warehouse, a partire da gs://.
  • PROJECT_ID: il tuo ID progetto Google Cloud .

Utilizzare i vettori di eliminazione binari

Per utilizzare i vettori di eliminazione binaria nelle tabelle Apache Iceberg V3, devi creare una tabella con la versione di formattazione 3, popolare la tabella con i dati, eseguire modifiche standard al database ed eseguire query sulla tabella. Puoi eseguire tutte le istruzioni create, insert, delete e update 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 3 utilizzando le istruzioni ALTER TABLE. Il downgrade di una tabella dalla versione 3 alla versione 2 non è supportato. Esegui la seguente istruzione in Spark SQL:

Spark 

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

Inserire dati nella tabella

Per garantire la generazione di file vettoriali di eliminazione binaria per le eliminazioni, il motore non deve eseguire il fallback alla copia in scrittura. In genere, prima dell'operazione di eliminazione, nella tabella deve essere presente una quantità significativa di dati. Ad esempio, Apache Spark potrebbe ottimizzare le piccole eliminazioni ricorrendo alla copia in scrittura. 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 vettoriali di eliminazione binaria 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 di 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 di vettori di eliminazione binari

Puoi verificare che i vettori di eliminazione binaria siano stati creati correttamente controllando la directory di archiviazione e i metadati dello snapshot.

Controllare i file .puffin

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

Esaminare i metadati dello 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