Utilizzare i vettori di eliminazione binaria nelle tabelle Iceberg V3

Il catalogo runtime Lakehouse supporta le tabelle Apache Iceberg V3. Una funzionalità principale della specifica Apache Iceberg V3 sono i vettori di eliminazione binari. Questa ottimizzazione archivia le eliminazioni a livello di riga nei file .puffin. Anziché eseguire join costosi in fase di 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 il rendimento nei seguenti modi:

  • Scritture di volumi elevati: migliora il rendimento 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.

Questa funzionalità è particolarmente utile per gestire aggiornamenti ed eliminazioni di volumi elevati nelle pipeline di acquisizione dei dati delle modifiche (CDC) o per soddisfare i requisiti normativi come il GDPR (diritto all'oblio) eliminando righe specifiche senza il sovraccarico della riscrittura di interi file di dati.

Prima di iniziare

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

  2. Abilita l'API BigLake.

    Ruoli necessari per abilitare le API

    Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin), che contiene l'autorizzazione serviceusage.services.enable. 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 nel progetto e nel 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.

Configurare 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 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 le tabelle V3 solo da BigQuery. Per creare e scrivere nelle 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. È consigliabile utilizzare 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 tabella e la sessione 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: l'ID del tuo Google Cloud progetto.

Utilizzare 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, popolare la tabella con i dati, eseguire modifiche standard del database ed eseguire query sulla tabella. Puoi eseguire tutte le istruzioni create, inserite, eliminate e aggiornate utilizzando Spark SQL.

Creare 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'
);

Eseguire l'upgrade di una tabella Iceberg V2 a V3

Puoi eseguire l'upgrade di una tabella Iceberg V2 esistente a V3 utilizzando le istruzioni ALTER TABLE. Il downgrade di una tabella da V3 a V2 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 che vengano generati file di vettori di eliminazione binari per le eliminazioni, il motore non deve eseguire il fallback a copy-on-write. In genere, è necessario che nella tabella sia presente una quantità significativa di dati prima dell'operazione di eliminazione. Ad esempio, Apache Spark potrebbe ottimizzare le eliminazioni di piccole dimensioni eseguendo il fallback a copy-on-write. Popola 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 contiene 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 contiene 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 di vettori di eliminazione binari 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'

Verificare la creazione di vettori di eliminazione binari

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

Controllare la presenza di file .puffin

Vai alla directory dei dati della tabella nel data 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.

Esaminare i metadati degli snapshot

I metadati degli 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 degli snapshot. In questo modo viene confermato che sono stati aggiunti file di eliminazione.

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

Passaggi successivi