Configurare le opzioni della tabella

Puoi utilizzare le opzioni della tabella nel catalogo di runtime Lakehouse per attivare l'interoperabilità di scrittura DML di BigQuery e la gestione delle tabelle (ottimizzazione automatica dello spazio di archiviazione) per le tue tabelle Apache Iceberg.

Per scoprire di più sui formati di tabella supportati e sulle funzionalità di attivazione nel catalogo di runtime di Lakehouse, consulta Confronta i tipi di tabella e Panoramica delle tabelle Apache Iceberg.

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

  3. Configura il catalogo di runtime Lakehouse con l'endpoint del catalogo REST Apache Iceberg.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per configurare le opzioni della tabella, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto e sul bucket di archiviazione:

  • Configura le proprietà della tabella in modalità di distribuzione delle credenziali: BigLake Editor (roles/biglake.editor) - il progetto
  • Configura le proprietà della tabella in modalità di distribuzione non delle credenziali:
    • BigLake Editor (roles/biglake.editor) - il progetto
    • Storage Object User (roles/storage.objectUser): il bucket Cloud Storage

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.

Considerazioni sulla configurazione

Quando configuri le opzioni della tabella, tieni presente i seguenti requisiti e comportamenti predefiniti:

Tabelle Iceberg supportate

Sebbene il catalogo di runtime Lakehouse supporti le tabelle Apache Iceberg V2 (GA) e V3 (anteprima), le funzionalità gestite (BigQuery DML e gestione delle tabelle) sono supportate solo per le tabelle Iceberg V2. Le tabelle Iceberg V1 non sono supportate. Per eseguire l'upgrade delle tabelle V1 esistenti, consulta Esegui l'upgrade delle tabelle Iceberg V1 alla versione V2.

Requisito di distribuzione delle credenziali

Per attivare la gestione delle tabelle, il catalogo di runtime Lakehouse deve avere la distribuzione delle credenziali abilitata a livello di catalogo. I job in background di gestione delle tabelle utilizzano il account di servizio di distribuzione delle credenziali per autenticare e aggiornare i file di dati di archiviazione sottostanti.

Abilita BigQuery DML

L'attivazione delle istruzioni DML (Data Manipulation Language) di BigQuery sblocca l'interoperabilità di scrittura da BigQuery sulle tabelle Apache Iceberg create utilizzando motori open source.

Le istruzioni supportate includono INSERT, UPDATE, DELETE e MERGE, oltre alle istruzioni DDL standard come CREATE TABLE, ALTER TABLE e DROP TABLE, ad eccezione di quelle non supportate nelle tabelle Apache Iceberg in BigQuery.

Abilita BigQuery DML per le nuove tabelle

Quando crei una tabella da BigQuery, BigQuery DML e la gestione delle tabelle sono abilitati per impostazione predefinita. Quando crei una tabella da motori open source, configura la proprietà della tabella gcp.biglake.bigquery-dml.enabled = true utilizzando la sintassi DDL del tuo motore.

Ad esempio, in Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Abilita BigQuery DML per le tabelle esistenti

Per abilitare BigQuery DML su una tabella esistente, aggiorna la proprietà della tabella.

Ad esempio, in Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = true);

Disattiva BigQuery DML

La disattivazione del DML di BigQuery rende la tabella di sola lettura per BigQuery e interrompe la gestione della tabella.

Ad esempio, in Spark SQL:

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.bigquery-dml.enabled' = false);

Abilita la gestione delle tabelle

La gestione delle tabelle automatizza i processi in background per ottimizzare lo spazio di archiviazione e gestire il ciclo di vita dei dati e dei metadati, ad esempio la compattazione e la garbage collection.

La gestione delle tabelle consente di eseguire le seguenti operazioni:

  • Scadenza degli snapshot e garbage collection: la scadenza degli snapshot gestisce la conservazione e l'eliminazione dei file di dati e metadati dagli snapshot delle tabelle. Questa operazione viene eseguita automaticamente in background dopo qualsiasi mutazione dei dati. Gli snapshot scadono in base alle proprietà della tabella Iceberg configurate dall'utente history.expire.max-snapshot-age-ms e history.expire.min-snapshots-to-keep sulla tabella. Rimuove le voci degli snapshot scaduti creando una definizione di snapshot aggiuntiva in un nuovo file di metadati che omette i riferimenti agli snapshot rimossi.

    • Limitazione: la scadenza degli snapshot e la garbage collection associata vengono ignorate se la tabella utilizza tag o rami. Per ulteriori informazioni, vedi Limitazioni.

    • Limitazione: la rimozione dei file orfani non è gestita dalla gestione delle tabelle. Per saperne di più, consulta Limiti.

  • Coalesce (compattazione): Coalesce è responsabile del mantenimento della forma dei dati, unendo file di piccole dimensioni in file più grandi. Coalesce viene eseguito automaticamente in background dopo qualsiasi mutazione dei dati. I file vengono selezionati per la compattazione se la loro dimensione media non compressa è inferiore al 50% della dimensione del file di destinazione di 256 MB. Ogni operazione di unione produce un nuovo snapshot della tabella. I job di unione in genere cedono il passo e riprovano dopo qualsiasi operazione DML in esecuzione. Tuttavia, per evitare la mancanza di ottimizzazione dello spazio di archiviazione a tempo indeterminato, viene attivato forzatamente un job di unione ogni 24 ore se i dati sono idonei per l'unione.

  • Monitoraggio dei job di gestione delle tabelle: tutti i job di gestione delle tabelle in background vengono registrati nella vista INFORMATION_SCHEMA.JOBS in BigQuery. Puoi eseguire query su questa vista per monitorare queste operazioni, in modo simile a come monitori altri job BigQuery. Per saperne di più sull'esecuzione di query sulle informazioni dei job, consulta Recupera i job di ottimizzazione dello spazio di archiviazione Iceberg.

    La frequenza dei job di gestione delle tabelle è direttamente correlata all'attività di mutazione dei dati. Inserimenti o aggiornamenti frequenti di piccole dimensioni attivano attività in background più frequenti. Potresti osservare periodi senza job in background se non sono presenti scritture nella tabella. Al contrario, volumi di scrittura elevati potrebbero comportare un'attività dei job più visibile in INFORMATION_SCHEMA.

Scegli se attivare la gestione dei tavoli

Per le tabelle Apache Iceberg gestite dal catalogo di runtime Lakehouse e pubblicate tramite l'endpoint del catalogo REST Apache Iceberg, puoi attivare la gestione delle tabelle o gestire autonomamente la manutenzione delle tabelle (ad esempio la compattazione e la scadenza degli snapshot) utilizzando motori open source o di terze parti.

Attiva la gestione dei tavoli (gcp.biglake.table-management.enabled = true) quando si applicano tutte le seguenti condizioni:

  • Vuoi la compattazione automatica dei file in background (coalesce) e la scadenza automatica degli snapshot e la garbage collection dopo le scritture di flussi di dati DML o open source.

  • Il tuo catalogo utilizza la modalità di distribuzione delle credenziali.

  • Una finestra di conservazione degli snapshot e di cronologia dei dati fino a 7 giorni (5 giorni per impostazione predefinita) soddisfa i tuoi requisiti.

  • La tabella soddisfa i requisiti per le funzionalità gestite (consulta Limitazioni).

Mantieni disattivata la gestione delle tabelle (l'impostazione predefinita per le tabelle create da motori open source o imposta gcp.biglake.table-management.enabled = false) e gestisci autonomamente la manutenzione delle tabelle se si applica una delle seguenti condizioni:

  • Esegui procedure di compattazione o manutenzione personalizzate in motori open source come Apache Spark, Apache Flink o Trino, soprattutto se le tabelle si basano su layout di ordinamento lineare o z-ordering che non vengono conservati dalla coalescenza.

  • Le tabelle utilizzano tag o rami di snapshot Apache Iceberg (che fanno sì che la gestione delle tabelle ignori la scadenza degli snapshot) o richiedono la conservazione degli snapshot e lo spostamento cronologico per più di 7 giorni.

  • Il tuo catalogo utilizza le credenziali dell'utente finale (autorizzazioni dirette di Cloud Storage Identity and Access Management (IAM)) anziché la modalità di distribuzione delle credenziali.

  • Le tabelle utilizzano funzionalità non supportate dalle funzionalità gestite (nel qual caso sia la gestione delle tabelle sia il DML di BigQuery devono rimanere disabilitati), come Apache Iceberg versione 3, modalità di unione in lettura, partizionamento su più colonne o IDENTITY o percorsi di archiviazione di dati dei clienti e metadati personalizzati. Per un elenco completo delle funzionalità non supportate, consulta Limitazioni.

Abilita la gestione delle tabelle per le nuove tabelle

Quando crei una tabella da BigQuery, DML e la gestione delle tabelle sono abilitati per impostazione predefinita. Quando crei una tabella da motori open source, configura la proprietà gcp.biglake.table-management.enabled. L'attivazione della gestione delle tabelle attiva automaticamente BigQuery DML se non è già attivo.

Ad esempio, in Spark SQL:

CREATE TABLE NAMESPACE.TABLE_NAME (id int, data string)
USING ICEBERG
TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

Attiva la gestione delle tabelle per le tabelle esistenti

Per attivare la gestione delle tabelle su una tabella esistente, aggiorna la proprietà della tabella.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = true);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "enabled");

Disattiva la gestione delle tabelle

La disattivazione della gestione delle tabelle impedisce l'accodamento di futuri job di ottimizzazione in background, anche se i job attivi in corso vengono completati. La disattivazione della gestione delle tabelle non disattiva BigQuery DML.

Spark SQL 

ALTER TABLE NAMESPACE.TABLE_NAME
SET TBLPROPERTIES ('gcp.biglake.table-management.enabled' = false);

BigQuery 

ALTER TABLE `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME`
SET OPTIONS (`properties.gcp.biglake.table-management` = "disabled");

Limitazioni

Le limitazioni per le funzionalità gestite (come l'interoperabilità di scrittura di BigQuery e la gestione delle tabelle) includono:

Limitazioni generali

  • Le funzionalità gestite sono supportate solo con le tabelle Apache Iceberg create nel catalogo di runtime di Lakehouse utilizzando l'endpoint del catalogo REST Apache Iceberg.
  • Tutte le limitazioni esistenti per le tabelle Apache Iceberg gestite da BigQuery si applicano alle operazioni con funzionalità gestite abilitate.
  • Le funzionalità gestite non sono supportate per le tabelle con Apache Iceberg format-version 3. Solo le tabelle con versione del formato 2 (specifica Iceberg v2) possono essere attivate per le funzionalità gestite.
  • Le funzionalità gestite non sono supportate per le tabelle con partizionamento avanzato, ad esempio il partizionamento per STRING, il partizionamento su più colonne o l'evoluzione delle partizioni.
  • Le funzionalità gestite non sono supportate per le tabelle configurate con ordinamenti (ad esempio, utilizzando la procedura WRITE ORDER BY o impostando write.distribution.mode = range).
  • Le funzionalità gestite non sono supportate per le tabelle Iceberg v2 che utilizzano la modalità di unione in lettura. Solo le tabelle che utilizzano la modalità di aggiornamento, eliminazione e unione copy-on-write possono essere attivate per le funzionalità gestite.
  • Le funzionalità gestite non supportano i file di dati compressi utilizzando i codec gzip, lz4 o brotli (write.parquet.compression-codec). Per i file di dati sono supportati solo i tipi di compressione zstd e snappy.
  • Le funzionalità gestite non sono supportate per le tabelle se lo schema contiene identificatori di chiave primaria nidificate (identifier-field-ids) che fanno riferimento a percorsi o campi nidificati in una struttura.
  • Le funzionalità gestite non sono supportate per le tabelle con località personalizzate per i dati o i metadati (write.data.path e write.metadata.path). Per contenere i file di dati e metadati è richiesta la località predefinita del bucket Cloud Storage.
  • Il clustering di BigQuery non è supportato per le tabelle Apache Iceberg gestite dal catalogo di runtime Lakehouse.
  • Se una tabella viene creata con il tipo di dati NUMERIC in BigQuery, gli aggiornamenti dello schema da Spark non vanno a buon fine perché Spark legge NUMERIC come NUMERIC(38,9). Come soluzione alternativa, quando crei tabelle con il tipo NUMERIC in BigQuery, imposta esplicitamente la precisione su NUMERIC(38,9).
  • Problema noto: l'eliminazione di una colonna in BigQuery utilizzando DDL (ALTER TABLE ... DROP COLUMN) seguita immediatamente dalla nuova aggiunta di una colonna con lo stesso nome non è supportata.

Limitazioni relative ai viaggi nel tempo

  • Quando la gestione delle tabelle è abilitata, il valore massimo consentito per la proprietà history.expire.max-snapshot-age-ms è 30 giorni (2592000000 ms) e il valore massimo consigliato è 7 giorni (604800000 ms). Il valore massimo consentito per la proprietà history.expire.min-snapshots-to-keep è 100.
  • Le configurazioni a livello di progetto o set di dati BigQuery per il viaggio nel tempo non si applicano. Sono attive solo le proprietà e i valori predefiniti della tabella Iceberg.

Limitazioni relative alla gestione delle tabelle

  • La scadenza degli snapshot viene ignorata per l'intera tabella se questa contiene snapshot con tag o rami. La conservazione personalizzata impostata utilizzando ALTER... RETAIN x DAYS viene ignorata, così come tutti i valori impostati per la proprietà history.expire.max-ref-age-ms. I motori open source possono comunque eseguire la scadenza degli snapshot.
  • La gestione delle tabelle non fa scadere gli schemi o le specifiche di partizione. Il file metadata.json conserva la cronologia completa degli schemi e delle specifiche di partizione, anche se nessuno snapshot fa riferimento a questi ID schema.

  • I file orfani creati da BigQuery o da motori open source non vengono eliminati dalla gestione delle tabelle. I motori open source possono eseguire la pulizia dei file orfani (ad esempio, utilizzando la procedura Spark remove_orphan_files con l'opzione prefix_listing impostata su true).

  • Coalesce non supporta l'ordinamento Z e l'ordinamento lineare. Se la tabella contiene queste proprietà, non è garantito che il layout venga mantenuto dopo l'esecuzione di COALESCE. Se le tabelle contengono queste proprietà, non attivare la gestione delle tabelle.

Limitazioni del partizionamento

  • Quando crei o registri tabelle da motori open source, le funzionalità gestite supportano solo il partizionamento sui tipi di campo DATE, DATETIME e TIMESTAMP con trasformazioni hour, day, month e year (ad eccezione della trasformazione hour sui campi DATE) e sui tipi di campo INTEGER.
  • Le funzionalità gestite non sono supportate nelle tabelle con trasformazioni IDENTITY. Devi specificare esplicitamente la trasformazione.
  • I comandi CREATE OR REPLACE sulle tabelle con funzionalità gestite sono supportati solo se utilizzano la stessa specifica di partizione. Le seguenti sostituzioni non sono supportate:
    • Sostituzione di una tabella non partizionata con una tabella partizionata.
    • Sostituzione di una tabella partizionata con una tabella non partizionata.
    • Sostituzione di una tabella partizionata con una tabella che utilizza una specifica di partizionamento diversa.
  • La denominazione dei campi di partizione personalizzati non è supportata. Le tabelle create o registrate da motori open source devono seguire la convenzione di denominazione dei campi di partizione predefinita del motore (aggiungendo _ e il nome della trasformazione, ad esempio _hour, _day, _month o _year). Ad esempio, per un campo denominato time_date che utilizza la trasformazione DAY, il valore del campo di partizione previsto è: json { "field-id": 1, "source-id": 1, "name": "time_date_day", "transform": transform }

Limitazioni relative alle proprietà delle tabelle Iceberg personalizzate

Le seguenti proprietà di comportamento della tabella non possono essere configurate su valori non predefiniti quando le funzionalità gestite sono abilitate. I valori predefiniti sono impostati come hardcoded quando viene attivata una funzionalità gestita:

Proprietà Valore predefinito Dettagli
format-version 2 Le funzionalità gestite supportano solo le tabelle Iceberg v2.
write.format.default parquet Le tabelle supportano solo file di dati in formato Parquet.
write.data.path table location + /data Per scrivere i file di dati viene utilizzato il percorso del bucket Cloud Storage predefinito configurato per l'endpoint del catalogo REST di Apache Iceberg.
write.metadata.path table location + /metadata Per scrivere i file di metadati, viene utilizzato il percorso del bucket Cloud Storage predefinito configurato per l'endpoint del catalogo REST di Apache Iceberg.
write.delete.mode copy-on-write I job di scrittura e gestione delle tabelle BigQuery supportano solo la copia su scrittura.
write.update.mode copy-on-write I job di scrittura e gestione delle tabelle BigQuery supportano solo la copia su scrittura.
write.merge.mode copy-on-write I job di scrittura e gestione delle tabelle BigQuery supportano solo la copia su scrittura.
write.delete.isolation-level Rilevamento rigoroso dei conflitti Le modifiche che alterano il file metadata.json (tra cui conflitti di dati, conflitti di metadati, letture fantasma o scritture simultanee non in conflitto) causano l'errore e il nuovo tentativo della transazione simultanea.
write.update.isolation-level Rilevamento rigoroso dei conflitti Stesso comportamento di write.delete.isolation-level.
write.merge.isolation-level Rilevamento rigoroso dei conflitti Stesso comportamento di write.delete.isolation-level.

Le seguenti proprietà possono essere configurate durante la creazione o la modifica di tabelle da motori open source:

Proprietà Valore predefinito Dettagli
write.parquet.compression-codec zstd L'ottimizzazione delle scritture e dello spazio di archiviazione di BigQuery supporta solo i formati di compressione zstd e snappy. Altri formati di compressione (come gzip, brotli e lz4) non sono supportati.
write.metadata.compression-codec null Può essere configurato su null o gzip.
history.expire.max-snapshot-age-ms 432000000 (5 giorni) Può essere configurato su qualsiasi numero intero non negativo fino a 2592000000 (30 giorni) quando la gestione delle tabelle è abilitata, con un massimo di 7 giorni (604800000 ms) consigliati. I job di gestione delle tabelle eliminano gli snapshot più vecchi della durata specificata.
history.expire.min-snapshots-to-keep 1 Può essere configurato su qualsiasi numero intero non negativo fino a 100 quando la gestione delle tabelle è abilitata. I job di gestione delle tabelle conservano almeno questo numero di snapshot.

Altre proprietà di scrittura di Apache Iceberg, come write.target-file-size-bytes e write.parquet.page-size-bytes, possono essere configurate dai motori open source, ma i job di scrittura e gestione delle tabelle di BigQuery potrebbero non essere conformi a queste proprietà.

Passaggi successivi