Accedi ai dati Iceberg da AlloyDB

L'accesso diretto a Iceberg in AlloyDB per PostgreSQL ti consente di eseguire query sui dati archiviati nel formato tabulare Apache Iceberg in Cloud Storage dalla tua istanza AlloyDB. Puoi accedere ai set di dati Iceberg utilizzando gli URI dei bucket Cloud Storage o il catalogo di runtime Lakehouse. Per accelerare i workload analitici, AlloyDB fornisce un motore colonnare integrato che ottimizza scansioni, join e aggregazioni. Grazie all'integrazione con il motore colonnare, l'accesso diretto a Iceberg ti consente di eseguire query analitiche ad alte prestazioni sul tuo data lakehouse senza creare, gestire o mantenere pipeline di dati di estrazione, trasformazione e caricamento (ETL) complesse.

Puoi eseguire query sulle tabelle Iceberg utilizzando i comandi SQL standard, unire i set di dati Iceberg alle tabelle operative in AlloyDB e compilare le tabelle Iceberg nel motore colonnare in memoria per prestazioni di query accelerate.

Vantaggi

L'accesso diretto a Iceberg offre i seguenti vantaggi:

  • Accesso al lakehouse zero-ETL: esegui query su set di dati Iceberg esterni in loco senza copiare o spostare i dati in sistemi di analisi separati.
  • Query transazionali e analitiche unificate: unisci i dati operativi in tempo reale archiviati nelle tabelle heap di AlloyDB con i dati storici di grandi dimensioni archiviati nelle tabelle Iceberg su Cloud Storage.
  • Integrazione flessibile del catalogo: accedi ai metadati delle tabelle Iceberg dai percorsi dei bucket Cloud Storage o tramite il catalogo di runtime Lakehouse.
  • Accelerazione delle query colonnari: memorizza nella cache e compila le tabelle Iceberg nella memoria del motore colonnare AlloyDB per un'elaborazione analitica in meno di un secondo.
  • Interfaccia SQL standard: utilizza la sintassi PostgreSQL familiare per eseguire query e analizzare le tabelle Iceberg.

Come funziona l'accesso diretto a Iceberg

L'accesso diretto a Iceberg utilizza l'interfaccia PostgreSQL Table Access Method (TAM) (USING iceberg) e si integra con il framework di pianificazione ed esecuzione del motore colonnare AlloyDB.

Quando esegui una query su una tabella Iceberg, AlloyDB opera in una delle seguenti modalità:

  • Scansione diretta (per letture in modalità flusso): AlloyDB legge i file di metadati e dati più recenti direttamente da Cloud Storage. Il motore colonnare elabora i dati in modalità flusso.
  • Accelerazione del motore colonnare (per le letture memorizzate nella cache in memoria): quando compili una tabella Iceberg nel motore colonnare AlloyDB utilizzando la funzione google_columnar_engine_add(), la tabella viene caricata nello spazio di archiviazione colonnare in memoria. Le query successive leggono dalla memoria del motore colonnare, massimizzando la velocità effettiva delle query e riducendo al minimo la latenza.

Pubblicazione di snapshot e aggiornamento della cache

Lo snapshot della tabella Iceberg su cui AlloyDB esegue le query dipende dalla modalità di lettura:

  • Scansione diretta: AlloyDB esegue query sull'ultimo snapshot Iceberg. All'avvio di una query, AlloyDB determina l'ultimo snapshot della tabella Iceberg disponibile e legge i dati da questo snapshot, anche all'interno di una transazione REPEATABLE READ o SERIALIZABLE. AlloyDB non supporta il blocco degli snapshot e le query point-in-time tra le transazioni.

    Ad esempio, quando esegui una query su una tabella utilizzando l'analisi diretta, ogni istruzione in una transazione legge dallo snapshot più recente disponibile:

    BEGIN TRANSACTION ISOLATION LEVEL SERIALIZABLE;
SELECT * FROM customer_orders;
-- If an external process commits a new Iceberg snapshot:
SELECT * FROM customer_orders; -- Returns results from the new snapshot.
COMMIT;

  • Accelerazione del motore colonnare: AlloyDB esegue le query nello snapshot compilato nel motore colonnare. Se AlloyDB scrive nuovi dati nella tabella Iceberg sottostante in Cloud Storage dopo la compilazione, le query potrebbero restituire dati obsoleti. Per ottenere dati aggiornati dopo le operazioni DML sulla tabella sottostante, aggiorna la cache utilizzando la funzione google_columnar_engine_refresh().

Tipi di dati supportati

Quando definisci una tabella Iceberg in AlloyDB, i nomi delle colonne e i tipi di dati nell'istruzione DDL devono corrispondere ai tipi nello schema Iceberg sottostante.

L'accesso diretto a Iceberg supporta i seguenti tipi di dati Apache Iceberg e i relativi tipi AlloyDB corrispondenti:

Tipo di dati Apache Iceberg Tipo di dati AlloyDB Descrizione
boolean BOOLEAN Conversione vettorizzata in formato byte-packed
int INT/INTEGER Numero intero con segno a 32 bit
long BIGINT Numero intero a 64 bit con segno
float REAL/FLOAT4 Rappresentazione in virgola mobile a precisione singola a 32 bit
double DOUBLE PRECISION/FLOAT8 Virgola mobile a precisione doppia a 64 bit
decimal(P, S) NUMERIC(P, S)/DECIMAL(P, S) Valore numerico a virgola fissa con precisione P e scala S
string TEXT/VARCHAR Valori di stringa UTF-8
date DATE Data di calendario (anno, mese, giorno)
timestamp TIMESTAMP Timestamp senza fuso orario
timestamptz TIMESTAMPTZ Timestamp con fuso orario

Limitazioni

L'accesso diretto a Iceberg presenta le seguenti limitazioni:

  • Disponibilità della versione di PostgreSQL: AlloyDB supporta l'accesso diretto a Iceberg su PostgreSQL 18 e versioni successive.
  • Autorizzazioni utente: solo gli utenti del database con il ruolo alloydbsuperuser possono creare tabelle Iceberg. Dopo aver creato una tabella, puoi concedere le autorizzazioni SELECT ad altri utenti per eseguire query sulla tabella Iceberg.
  • Operazioni di sola lettura: AlloyDB supporta solo query SELECT (DQL) sulle tabelle Iceberg. Non supporta le operazioni di scrittura (INSERT, UPDATE, DELETE, TRUNCATE).
  • Versione della specifica Apache Iceberg: AlloyDB non supporta i file di eliminazione Iceberg v2 (eliminazioni posizionali e di uguaglianza) o i vettori di eliminazione Iceberg v3.
  • Supporto dei formati file: l'accesso diretto a Iceberg supporta i file di dati Parquet e i file di metadati JSON e Avro. Non supporta i file di dati ORC.
  • Controllo delle versioni degli snapshot: le query di scansione diretta vengono eseguite sull'ultimo snapshot della tabella Iceberg e le query con accelerazione colonnare vengono eseguite sullo snapshot compilato. AlloyDB non supporta le query point-in-time.
  • Evoluzione dello schema: AlloyDB non supporta le operazioni ALTER TABLE sulle tabelle Iceberg. La tabella Iceberg sottostante non deve aver subito una migrazione dello schema.
  • Supporto del catalogo dei metadati: l'accesso diretto a Iceberg supporta i percorsi diretti dei bucket Cloud Storage (gs://) e i percorsi del catalogo di runtime Lakehouse (bl://). Per il catalogo di runtime Lakehouse, AlloyDB supporta solo la modalità delle credenziali dell'utente finale. Non supporta la modalità di distribuzione delle credenziali o altri cataloghi REST.
  • Bucket con Pagamenti a carico del richiedente: AlloyDB non supporta i bucket Cloud Storage che utilizzano Pagamenti a carico del richiedente.
  • Vincolo di popolazione completa: AlloyDB non supporta la popolazione colonnare parziale per le tabelle Iceberg. Le tabelle devono rientrare nella memoria del motore colonnare o nello spazio SSD.
  • Memoria heap di popolazione: la compilazione di una tabella Iceberg che contiene gruppi di righe Parquet di grandi dimensioni potrebbe superare il limite di memoria heap di popolazione per worker, soprattutto nelle istanze con meno vCPU. Per risolvere il problema, consulta L'heap di popolazione del motore colonnare è pieno.

Prima di iniziare

Prima di creare ed eseguire query sulle tabelle Iceberg, assicurati di completare quanto segue:

  1. Crea un cluster AlloyDB che esegue PostgreSQL 18 o versioni successive su Google Cloud. Per saperne di più, consulta Crea un cluster.
  2. Ospita una tabella Apache Iceberg in Cloud Storage o registrata nel catalogo di runtime Lakehouse:
    • Per i percorsi di Cloud Storage, la struttura della directory del bucket deve seguire il layout standard di Apache Iceberg contenente le sottodirectory data/ e metadata/, inclusi i file JSON dei metadati e version-hint.text. Per saperne di più, consulta Crea un bucket.
    • Per il catalogo di runtime Lakehouse, crea e registra il tuo catalogo Iceberg in modalità credenziali utente finale. Per saperne di più, consulta Configura l'endpoint del catalogo REST Apache Iceberg.
  3. Configura le credenziali del database per un utente con il ruolo alloydbsuperuser. Per saperne di più, vedi Ruolo del gruppo alloydbsuperuser.

Ruoli obbligatori

Per consentire ad AlloyDB di leggere i dati e i metadati di Iceberg, devi concedere i ruoli IAM richiesti al account di servizio del cluster AlloyDB:

  • Accesso a Cloud Storage: concedi il ruolo Storage Object Viewer (roles/storage.objectViewer) sul bucket Cloud Storage contenente i dati e i metadati Iceberg.
  • Accesso a BigLake (se utilizzi il catalogo di runtime Lakehouse): concedi il ruolo BigLake Viewer (roles/biglake.viewer) al progetto che ospita il catalogo BigLake.

Per trovare il account di servizio del cluster, esegui il comando gcloud beta alloydb clusters describe:

gcloud beta alloydb clusters describe CLUSTER_ID --region=REGION_ID

Sostituisci quanto segue:

  • CLUSTER_ID: l'ID cluster AlloyDB.
  • REGION_ID: la località del cluster AlloyDB. Ad esempio, us-east1. Per un elenco completo delle regioni, consulta Località di AlloyDB.

L'output contiene un campo serviceAccountEmail, che è il account di servizio per questo cluster. Nella console Google Cloud , puoi trovare il account di servizio nella pagina Panoramica del cluster.

Per concedere il ruolo Visualizzatore oggetti Storage utilizzando gcloud CLI, esegui:

gcloud storage buckets add-iam-policy-binding \
    gs://BUCKET_NAME \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/storage.objectViewer"

Se utilizzi il catalogo di runtime Lakehouse, concedi il ruolo BigLake Viewer:

gcloud projects add-iam-policy-binding LAKEHOUSE_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role="roles/biglake.viewer"

Sostituisci quanto segue:

  • BUCKET_NAME: il nome del bucket Cloud Storage.
  • LAKEHOUSE_PROJECT_ID: l'ID progetto Google Cloud in cui è ospitato il catalogo di runtime Lakehouse.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio del cluster che hai trovato nel campo serviceAccountEmail.

Configura flag di database

Per attivare il motore colonnare e l'accesso diretto a Iceberg, puoi configurare i flag di database nell'istanza AlloyDB. Imposta i seguenti flag di database nell'istanza:

Flag di database Valore Descrizione
google_columnar_engine.enabled on Abilita il motore colonnare AlloyDB.
google_columnar_engine.enable_iceberg_reads on Abilita l'accesso diretto a Iceberg. È richiesto il riavvio dell'istanza.
google_columnar_engine.memory_size_in_mb SIZE_IN_MB (Facoltativo) Alloca la memoria al motore colonnare. Opzione consigliata se prevedi di compilare le tabelle Iceberg in memoria.

Per configurare questi flag utilizzando gcloud CLI, esegui il comando gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --database-flags=google_columnar_engine.enabled=on,google_columnar_engine.enable_iceberg_reads=on

Sostituisci quanto segue:

  • INSTANCE_ID: l'ID dell'istanza AlloyDB.
  • CLUSTER_ID: l'ID del tuo cluster AlloyDB.
  • REGION_ID: l'ID regione del tuo cluster AlloyDB.

Crea una tabella Iceberg in AlloyDB

Per esporre un set di dati Apache Iceberg in AlloyDB, connettiti come utente con privilegi alloydbsuperuser. Quindi, crea una tabella utilizzando il metodo di accesso alla tabella USING iceberg.

CREATE TABLE TABLE_NAME (
    COLUMN_NAME DATA_TYPE [, ...]
)
USING iceberg
WITH (
    uri = 'LOCATION_URI'
);

Sostituisci quanto segue:

  • TABLE_NAME: il nome della tabella da creare in AlloyDB.
  • COLUMN_NAME e DATA_TYPE: le definizioni delle colonne. I nomi e i tipi di colonna devono corrispondere allo schema della tabella Iceberg sottostante.
  • LOCATION_URI: la posizione dei metadati della tabella Iceberg. Specifica uno dei seguenti formati:
    • Percorso Cloud Storage diretto: gs://BUCKET_NAME/PATH_TO_ICEBERG_TABLE
    • URI del catalogo di runtime Lakehouse: bl://projects/PROJECT_ID/catalogs/CATALOG_NAME/databases/DATABASE_NAME/tables/TABLE_NAME

Esempi

Gli esempi seguenti mostrano come creare tabelle Iceberg in AlloyDB.

Crea una tabella da un percorso Cloud Storage

L'esempio seguente crea una tabella denominata customer_orders supportata da un set di dati Iceberg che si trova in un bucket Cloud Storage:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'gs://my-iceberg-analytics-bucket/datasets/sales/customer_orders'
);

Crea una tabella dal catalogo di runtime Lakehouse

L'esempio seguente crea una tabella che fa riferimento a una tabella Iceberg gestita dal catalogo di runtime di Lakehouse:

CREATE TABLE customer_orders (
    order_id BIGINT,
    customer_id INT,
    order_status TEXT,
    total_amount DOUBLE PRECISION,
    order_date DATE,
    is_completed BOOLEAN
)
USING iceberg
WITH (
    uri = 'bl://projects/my-analytics-project/catalogs/sales_catalog/databases/retail_db/tables/customer_orders'
);

Esegui query sui dati Iceberg

Dopo aver creato la tabella in AlloyDB, puoi eseguire query utilizzando istruzioni SQL standard SELECT con privilegi alloydbsuperuser. Facoltativamente, puoi concedere le autorizzazioni in lettura a un utente senza privilegi alloydbsuperuser utilizzando l'istruzione GRANT. Ad esempio, GRANT SELECT ON customer_orders TO normal_user.

Esegui query sui dati

L'esempio seguente mostra come eseguire una query:

SELECT
    customer_id,
    COUNT(order_id) AS total_orders,
    SUM(total_amount) AS total_spent
FROM customer_orders
WHERE is_completed = true
  AND order_date >= '2026-01-01'
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10;

Esegui query sui dati Iceberg uniti ai dati operativi

Puoi combinare i dati operativi in tempo reale che si trovano in AlloyDB con i dati storici che si trovano in Iceberg:

SELECT
    c.customer_name,
    c.account_tier,
    COUNT(o.order_id) AS total_orders,
    SUM(o.total_amount) AS historical_spend
FROM customer_orders o
JOIN customers c ON o.customer_id = c.customer_id
WHERE o.is_completed = true
GROUP BY c.customer_name, c.account_tier
ORDER BY historical_spend DESC;

Importa i dati in una tabella locale

Per creare una copia indipendente e scrivibile dei dati Iceberg nello spazio di archiviazione AlloyDB locale, esegui CREATE TABLE ... AS SELECT, come mostrato nell'esempio seguente:

CREATE TABLE local_customer_orders AS
SELECT * FROM customer_orders
WHERE order_date >= '2026-01-01';

Accelera le query utilizzando il motore colonnare

Per i workload analitici che richiedono una latenza ultra bassa, puoi compilare la tabella Iceberg direttamente nella memoria del motore colonnare di AlloyDB.

Compila la tabella Iceberg nell'archivio colonnare

Per compilare tutte le colonne di una tabella Iceberg nel motore colonnare di AlloyDB, utilizza la funzione google_columnar_engine_add(). Ad esempio:

SELECT google_columnar_engine_add('customer_orders');

Per compilare solo colonne specifiche utilizzate dalle query, passa un elenco di nomi di colonne separati da virgole come secondo argomento. Ad esempio:

SELECT google_columnar_engine_add('customer_orders', 'customer_id,order_status');

Per saperne di più, consulta Aggiungi colonne utilizzando le funzioni SQL.

Aggiorna i dati compilati

Se scrivi nuovi snapshot nel set di dati Iceberg sottostante, aggiorna la tabella per ricaricare i dati più recenti nel motore colonnare in modo che le query restituiscano risultati aggiornati:

SELECT google_columnar_engine_refresh('customer_orders');

Rimuovi una tabella dall'archivio colonnare

Per rimuovere una tabella Iceberg dall'archivio colonnare e tornare alla scansione diretta:

SELECT google_columnar_engine_drop('customer_orders');

Monitora e verifica l'esecuzione delle query

Puoi monitorare il modo in cui AlloyDB esegue le query sulle tabelle Iceberg e verificare se le query utilizzano il motore colonnare in memoria. Utilizza le viste di sistema per controllare lo stato di completamento della cache e EXPLAIN per esaminare i piani di esecuzione delle query.

Verifica lo stato della memorizzazione nella cache colonnare

Per verificare se una tabella Iceberg è compilata nel motore colonnare, esegui una query sulla vista di sistema g_columnar_relations:

SELECT relation_name, status
FROM g_columnar_relations
WHERE relation_name = 'customer_orders';

Un valore status di USABLE conferma che la tabella è memorizzata nella cache del motore colonnare.

Esamina i piani di esecuzione delle query con EXPLAIN

Per verificare se una query utilizza il motore colonnare, utilizza l'istruzione EXPLAIN:

EXPLAIN (ANALYZE, COSTS OFF)
SELECT SUM(total_amount)
FROM customer_orders
WHERE is_completed = true;

L'output indica l'esecuzione colonnare tramite un nodo Custom Scan (ColumnarScan) sulla tabella:

Custom Scan (ColumnarScan) on customer_orders
  Filter: (is_completed = true)

Risoluzione dei problemi

Questa sezione descrive come risolvere i problemi comuni durante la configurazione e l'esecuzione di query sulle tabelle Iceberg in AlloyDB.

Il flag google_columnar_engine.enable_iceberg_reads è disattivato

Causa: il flag di database per l'accesso diretto a Iceberg è disabilitato.

Correzione consigliata: imposta i flag di database google_columnar_engine.enabled=on e google_columnar_engine.enable_iceberg_reads=on nell'istanza e riavvia l'istanza.

Autorizzazione negata per l'accesso a Cloud Storage

Causa: il account di servizio del cluster AlloyDB non dispone dell'accesso in lettura al bucket Cloud Storage.

Correzione consigliata: concedi il ruolo roles/storage.objectViewer al account di servizio del cluster sul bucket.

Autorizzazione negata per l'accesso al catalogo di runtime Lakehouse

Causa: il account di servizio del cluster AlloyDB non dispone dell'accesso in lettura al catalogo di runtime di Lakehouse.

Correzione consigliata: concedi il ruolo roles/biglake.viewer al service account del cluster nel progetto Google Cloud che ospita il catalogo di runtime di Lakehouse.

Popolamento delle colonne non riuscito

Causa: le dimensioni della tabella Iceberg superano la memoria e lo spazio SSD disponibili nel motore colonnare.

Correzione consigliata: aumenta l'allocazione della memoria al motore colonnare utilizzando il flag google_columnar_engine.memory_size_in_mb nell'istanza o aumenta le dimensioni della cache di archiviazione del motore colonnare utilizzando il flag google_columnar_engine.storage_cache_size. Per saperne di più, consulta Configura la cache di archiviazione per il motore colonnare.

L'heap di popolazione del motore colonnare è pieno

Messaggio di errore:

ERROR: Columnar engine population heap is full during population. Set
google_columnar_engine.population_heap_size_in_mb to a bigger value.

Causa: la memoria richiesta per compilare un gruppo di righe Parquet di grandi dimensioni supera il limite di heap di popolazione per worker.

Correzione consigliata: riduci il numero di worker di popolazione paralleli in modo che il processo di popolazione possa utilizzare un heap più grande. Nella sessione SQL in cui compili la tabella, imposta il flag google_job_scheduler.max_parallel_workers_per_job su 0 prima di chiamare la funzione google_columnar_engine_add():

SET google_job_scheduler.max_parallel_workers_per_job = 0;
SELECT google_columnar_engine_add('TABLE_NAME');

Sostituisci TABLE_NAME con il nome della tabella Iceberg in AlloyDB.

Passaggi successivi