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 di runtime Lakehouse. Queste opzioni fungono da impostazioni di base che estendono le funzionalità per le operazioni sulla tabella.

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

Quando utilizzi le tabelle nel catalogo di runtime Lakehouse, è utile comprendere i diversi tipi di tabelle e le relative funzionalità di attivazione. Per scoprire di più sull'utilizzo delle tabelle Apache Iceberg, consulta la panoramica delle tabelle Apache Iceberg.

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

  3. Configura il catalogo di runtime Lakehouse catalog 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:
    • Editor BigLake (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

Tieni presente i seguenti requisiti e comportamenti predefiniti quando configuri le opzioni della tabella:

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 a V2.

Requisito di distribuzione delle credenziali

Per attivare la gestione automatica 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 l'account di servizio di distribuzione delle credenziali per autenticare e aggiornare i file di dati di archiviazione sottostanti.

Abilitare BigQuery DML

L'abilitazione delle istruzioni data manipulation language (DML) 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, 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.

Abilitare 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 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);

Disabilitare BigQuery DML

La disabilitazione di BigQuery DML rende la tabella di sola lettura per BigQuery e interrompe la gestione automatica delle tabelle.

Ad esempio, in Spark SQL:

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

Abilitare 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 nella tabella. Rimuove le voci degli snapshot scaduti dal file metadata.json, seguita dall'eliminazione fisica dei file di dati e metadati che appartenevano solo agli snapshot scaduti e a cui non fanno più riferimento gli snapshot attivi.

    • Limitazione: la scadenza degli 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 viene eseguita 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. In genere, i job di unione vengono eseguiti e riprovati dopo qualsiasi operazione DML in esecuzione. Tuttavia, per evitare una carenza indefinita di ottimizzazione dello spazio di archiviazione, un job di unione viene attivato forzatamente 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 visualizzazione INFORMATION_SCHEMA.JOBS di BigQuery. Puoi eseguire query su questa visualizzazione per monitorare queste operazioni, in modo simile a come monitori altri job di BigQuery. Per saperne di più sull'esecuzione di query sulle 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. Gli inserimenti o gli aggiornamenti di piccole dimensioni frequenti attivano attività in background più frequenti. Potresti osservare periodi senza job in background se non vengono eseguite scritture nella tabella. Al contrario, volumi di scrittura elevati potrebbero comportare un'attività di 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 su 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);

Disabilitare la gestione delle tabelle

La disabilitazione della gestione delle tabelle impedisce l'accodamento di futuri job di ottimizzazione in background, anche se i job attivi in corso verranno completati. La disabilitazione della gestione delle tabelle non disabilita 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 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 Apache Iceberg.
  • Tutte le limitazioni esistenti per le tabelle Apache Iceberg gestite da BigQuery si applicano alle operazioni con le funzionalità gestite abilitate.
  • Le funzionalità gestite non sono supportate per le tabelle con Apache Iceberg format-version 3. Solo le tabelle format-version 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 a 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 di copia in scrittura 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 posizioni di dati o metadati personalizzate (write.data.path e write.metadata.path). Per contenere i file di dati e metadati è necessaria 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, 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 dalla riaggiunta di una colonna con lo stesso nome non è supportata.

Limitazioni relative allo spostamento cronologico

  • Quando la gestione delle tabelle è abilitata, il valore massimo consigliato per la proprietà history.expire.max-snapshot-age-ms è di 7 giorni.
  • Le configurazioni a livello di progetto o set di dati di BigQuery per lo spostamento cronologico non si applicano. Sono attive solo le proprietà e le impostazioni predefinite delle tabelle Iceberg.

Limitazioni relative alla gestione delle tabelle

  • La scadenza degli snapshot viene saltata 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 history.expire.max-ref-age-ms proprietà 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 delle partizioni. Il file metadata.json conserva la cronologia completa degli schemi e delle specifiche delle partizioni, anche se nessuno snapshot fa riferimento a questi ID schema.

  • I file orfani creati da BigQuery o dai 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).

  • L'unione 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 dell'unione. Se le tabelle contengono queste proprietà, la cosa migliore è non abilitare 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, TIMESTAMP, e TIMESTAMPTZ con le trasformazioni hour, day, month, e year (ad eccezione della trasformazione hour sui campi DATE).
  • Le funzionalità gestite non sono supportate per le 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. 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 personalizzata dei campi di partizione 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à personalizzate delle tabelle Iceberg

Le seguenti proprietà del comportamento delle tabelle non possono essere configurate con valori non predefiniti quando le funzionalità gestite sono abilitate. I valori predefiniti sono hardcoded 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 Per scrivere i file di dati viene utilizzato il percorso predefinito del bucket Cloud Storage configurato per il catalogo REST Lakehouse.
write.metadata.path table location + /metadata Per scrivere i file di metadati viene utilizzato il percorso predefinito del bucket Cloud Storage configurato per il catalogo REST Lakehouse.
write.delete.mode copy-on-write I job di scrittura e gestione delle tabelle di BigQuery supportano solo la copia in scrittura.
write.update.mode copy-on-write I job di scrittura e gestione delle tabelle di BigQuery supportano solo la copia in scrittura.
write.merge.mode copy-on-write I job di scrittura e gestione delle tabelle di 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 delle tabelle da motori open source:

Proprietà Valore predefinito Dettagli
write.parquet.compression-codec zstd I job di scrittura e ottimizzazione dello spazio di archiviazione di BigQuery supportano solo i formati di compressione zstd e snappy. Gli 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 più vecchi della 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 di BigQuery potrebbero non rispettarle.

Passaggi successivi