Configurare le opzioni della tabella

La configurazione delle opzioni della tabella consente di attivare l'interoperabilità di scrittura di BigQuery o la gestione delle tabelle (ottimizzazione automatica dello spazio di archiviazione) per le tabelle Apache Iceberg nel catalogo runtime Lakehouse. Queste opzioni fungono da impostazioni di base che estendono le funzionalità per le operazioni sulla tabella.

Configurando proprietà specifiche della tabella, puoi attivare l'interoperabilità di scrittura con BigQuery DML o attivare la gestione automatica delle tabelle (ottimizzazione dell'archiviazione).

Quando utilizzi le tabelle nel catalogo del runtime Lakehouse, è utile comprendere i diversi tipi di tabelle e le relative funzionalità di attivazione. Per saperne di più sull'utilizzo delle tabelle Apache Iceberg in particolare, consulta 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 disponi già di questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  3. Configura il catalogo 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: Editor BigLake (roles/biglake.editor): il progetto
  • Configura le proprietà della tabella in modalità di distribuzione delle credenziali non automatica:
    • 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

Sono supportate solo le tabelle Apache Iceberg V2 (GA) e V3 (anteprima). Le tabelle Iceberg V1 non sono supportate. Per eseguire l'upgrade delle tabelle V1 esistenti, consulta Eseguire l'upgrade delle tabelle Iceberg V1 alla versione V2.

Requisito di distribuzione delle credenziali

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

Abilita BigQuery DML

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

Le istruzioni supportate includono INSERT, UPDATE, DELETE e MERGE, nonché le 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 automatica 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 motore.

Ad esempio, in Spark SQL:

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

Abilitare il linguaggio DML di BigQuery 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

Se disattivi BigQuery DML, la tabella diventa di sola lettura per BigQuery e la gestione automatica delle tabelle viene interrotta.

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 l'archiviazione e gestire il ciclo di vita di dati e metadati, ad esempio la compattazione e la garbage collection.

La gestione delle tabelle ti 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 sono scaduti in base alle proprietà della tabella Iceberg configurate dall'utente history.expire.max-snapshot-age-ms e history.expire.min-snapshots-to-keep nella tabella. Rimuove le voci di snapshot scadute creando un'altra definizione di snapshot aggiuntiva che si manifesta in un nuovo file di metadati che non include più riferimenti agli snapshot rimossi.

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

    • Limitazione: la rimozione dei file orfani non viene gestita dalla gestione automatica delle tabelle. Per ulteriori informazioni, vedi Limitazioni.

  • Unione (compattazione): l'unione è responsabile del mantenimento della forma dei dati, unendo i file di piccole dimensioni in file più grandi. L'unione delle esecuzioni viene eseguita automaticamente in background dopo qualsiasi mutazione dei dati. I file vengono selezionati per la compattazione se le loro dimensioni medie non compresse sono inferiori al 50% delle dimensioni 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 l'ottimizzazione dello spazio di archiviazione, viene attivato forzatamente un job di unione ogni 24 ore se i dati sono idonei all'unione.

  • Monitoraggio dei job di gestione delle tabelle:tutti i job di gestione delle tabelle in background vengono registrati nella vista INFORMATION_SCHEMA.JOBS di 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'interrogazione delle informazioni sui job, consulta Recuperare 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. Piccoli inserimenti o aggiornamenti frequenti attivano attività in background più frequenti. Potresti notare periodi senza job in background se non vengono eseguite scritture nella tabella. Al contrario, volumi di scrittura elevati potrebbero comportare un'attività dei job più visibile in INFORMATION_SCHEMA.

Abilitare la gestione delle tabelle per le nuove tabelle

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

Ad esempio, in Spark SQL:

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

Abilitare la gestione delle tabelle per le tabelle esistenti

Per abilitare la gestione delle tabelle in una tabella esistente, aggiorna la proprietà della tabella.

Ad esempio, in Spark SQL:

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

Disattivare la gestione delle tabelle

La disattivazione della gestione delle tabelle impedisce la messa in coda di futuri job di ottimizzazione in background, anche se i job attivi in corso verranno 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

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

Limitazioni generali

  • Le funzionalità gestite sono supportate solo con le tabelle Apache Iceberg create nel catalogo di runtime Lakehouse utilizzando l'endpoint del catalogo REST di Apache Iceberg.
  • Tutte le limitazioni esistenti per le tabelle Apache Iceberg gestite da BigQuery si applicano alle operazioni con le funzionalità gestite attivate.
  • Le funzionalità gestite non sono supportate per le tabelle con Apache Iceberg formato versione 3. Solo le tabelle in formato versione 2 (specifica Iceberg v2) possono essere attivate per le funzionalità gestite.
  • Le funzionalità gestite non sono supportate per le tabelle con partizionamento avanzato, come 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 ordini di ordinamento (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 nidificati (identifier-field-ids) che fanno riferimento a percorsi o campi nidificati in una struttura.
  • Le funzionalità gestite non sono supportate per le tabelle con dati o posizioni dei metadati personalizzate (write.data.path e write.metadata.path). Per contenere i file di dati e metadati è necessaria la posizione predefinita del bucket Cloud Storage.
  • Il clustering BigQuery non è supportato per le tabelle Apache Iceberg gestite dal catalogo runtime Lakehouse.
  • Se una tabella viene creata con il tipo di dati NUMERIC in BigQuery, tutti gli aggiornamenti dello schema da Spark non andranno 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 dal reintegro di una colonna con lo stesso nome non è supportata.

Limitazioni relative ai viaggi nel tempo

  • Quando la gestione delle tabelle è attivata, il valore massimo consigliato per la proprietà history.expire.max-snapshot-age-ms è 7 giorni.
  • Le configurazioni a livello di progetto o set di dati BigQuery per il time travel 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 la tabella contiene snapshot con tag o rami. La conservazione personalizzata impostata utilizzando ALTER... RETAIN x DAYS viene ignorata e tutti i valori impostati per la proprietà history.expire.max-ref-age-ms vengono ignorati. I motori open source possono comunque eseguire la scadenza degli snapshot.
  • La gestione automatica 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 delle partizioni, anche se nessuna istantanea fa riferimento a questi ID schema.

  • I file orfani creati da BigQuery o da motori open source non vengono puliti dalla gestione automatica 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).

  • Unisci non supporta l'ordinamento Z e quello lineare. Se la tabella contiene queste proprietà, non è garantito che il layout venga mantenuto dopo l'esecuzione dell'unione. Se le tue tabelle contengono queste proprietà, la soluzione migliore è non attivare la gestione delle tabelle.

Limitazioni relative al partizionamento

  • Quando crei o registri tabelle da motori open source, le funzionalità gestite supportano solo il partizionamento sui tipi di campi DATE, DATETIME e TIMESTAMP con le trasformazioni hour, day, month e year (ad eccezione della trasformazione hour sui campi DATE) e sui tipi di campi INTEGER.
  • Le funzionalità gestite non sono supportate nelle tabelle con trasformazioni IDENTITY. Gli utenti devono specificare esplicitamente la trasformazione.
  • I comandi CREATE OR REPLACE sulle tabelle con funzionalità gestite sono supportati solo se utilizzano la stessa specifica di partizione. I seguenti sostituzioni non sono supportate:
    • Sostituzione di una tabella non partizionata con una tabella partizionata.
    • Sostituzione di una tabella partizionata con una non partizionata.
    • Sostituzione di una tabella partizionata con una tabella che utilizza una specifica di partizionamento diversa.
  • La denominazione personalizzata dei campi di partizione non è supportata. Le tabelle create o registrate da motori open source devono seguire la convenzione di denominazione del campo di partizione predefinito del motore (aggiungendo _ e il nome della trasformazione, ad esempio _hour, _day, _month o _year). Ad esempio, per un campo denominato time_date utilizzando 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à personalizzate delle tabelle Iceberg

Le seguenti proprietà del comportamento della tabella non possono essere configurate su valori diversi da quelli predefiniti quando sono abilitate le funzionalità gestite. I valori predefiniti sono codificati quando è abilitata 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 i file di dati in formato Parquet.
write.data.path table location + /data Il percorso del bucket Cloud Storage predefinito configurato per l'endpoint del catalogo REST di Apache Iceberg viene utilizzato per scrivere i file di dati.
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 in scrittura.
write.update.mode copy-on-write I job di scrittura e gestione delle tabelle BigQuery supportano solo la copia in scrittura.
write.merge.mode copy-on-write I job di scrittura e gestione delle tabelle BigQuery supportano solo la copia in scrittura.
write.delete.isolation-level Rilevamento rigoroso dei conflitti Le modifiche che modificano il file metadata.json (inclusi 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 della scrittura e dell'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 positivo, ma è consigliato fino a 7 giorni (604800000 ms) quando la gestione delle tabelle è abilitata. I job di gestione delle tabelle eliminano gli snapshot precedenti alla durata specificata.
history.expire.min-snapshots-to-keep 1 Può essere configurato su qualsiasi numero intero positivo. 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 da motori open source, ma i job di scrittura e gestione delle tabelle BigQuery potrebbero non rispettarle.

Passaggi successivi