Eseguire una query su una tabella.

L'esecuzione di query su una tabella legge i dati dai file Cloud Storage sottostanti utilizzando i metadati gestiti dal catalogo del runtime Lakehouse.

Puoi eseguire query da motori open source come Spark e Trino o direttamente da BigQuery utilizzando una sintassi del nome della tabella in quattro parti (sintassi P.C.N.T).

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 eseguire query su una tabella, chiedi all'amministratore di concederti i seguenti ruoli IAM sul progetto e sul bucket di archiviazione:

  • Leggi i dati della tabella in modalità di distribuzione delle credenziali: Visualizzatore BigLake (roles/biglake.viewer): il progetto
  • Leggere i dati della tabella in modalità di distribuzione delle credenziali:
    • BigLake Viewer (roles/biglake.viewer) - il progetto
    • Storage Object Viewer (roles/storage.objectViewer): 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.

Funzionalità e supporto delle tabelle

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.

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.

Utilizzare le opzioni della tabella (anteprima)

Puoi attivare l'utilizzo delle funzionalità gestite di BigQuery, come il DML (Data Manipulation Language) di BigQuery e la gestione automatica delle tabelle, configurando proprietà specifiche delle tabelle. Queste funzionalità vengono attivate in modi diversi a seconda di dove viene creata la tabella:

  • Da BigQuery:BigQuery DML e la gestione automatica delle tabelle sono abilitati per impostazione predefinita.
  • Dai motori open source:per attivare la funzionalità, devi configurare esplicitamente le proprietà della tabella. Per saperne di più, consulta Configurare le opzioni della tabella.

Quando esegui query sulle tabelle da BigQuery, puoi accedere alle tabelle Iceberg standard e a quelle abilitate per le funzionalità gestite di BigQuery. Consulta Configurare le opzioni della tabella per istruzioni dettagliate.

Eseguire una query su una tabella.

Seleziona tutti i dati della tabella:

Spark 

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino 

SELECT * FROM TABLE_NAME;

BigQuery

Per eseguire query sulle tabelle Apache Iceberg nel catalogo del runtime Lakehouse da BigQuery, utilizza il nome della tabella in quattro parti nella query con il seguente formato: PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME.

SELECT * FROM `PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Sostituisci i seguenti valori:

  • PROJECT_NAME: il Google Cloud progetto proprietario del catalogo nel catalogo del runtime Lakehouse. Il progettoGoogle Cloud selezionato nella console Google Cloud viene fatturato per la query.

  • CATALOG_ID: l'ID del catalogo runtime Lakehouse specificato al momento della creazione del catalogo. Questo identificatore viene utilizzato come nome del catalogo nelle query BigQuery.

    Questo identificatore è anche il nome del bucket Cloud Storage.

    Ad esempio, se hai creato il bucket per archiviare il catalogo e l'hai chiamato iceberg-bucket, sia il nome del catalogo sia il nome del bucket sono iceberg-bucket. Questo valore viene utilizzato in un secondo momento quando esegui query sul catalogo in BigQuery, utilizzando la sintassi P.C.N.T. Ad esempio my-project.catalog_id.quickstart_namespace.quickstart_table.

  • NAMESPACE_OR_SCHEMA_NAME: lo spazio dei nomi della tabella se utilizzi Spark o il nome dello schema della tabella se utilizzi Trino.

  • TABLE_NAME: il nome della tabella.

Esegui query utilizzando Time Travel

Puoi eseguire query sui dati storici delle tabelle Apache Iceberg gestite utilizzando lo spostamento temporale. Puoi eseguire il time travel da BigQuery utilizzando la clausola FOR SYSTEM_TIME AS OF o da motori open source come Spark utilizzando ID snapshot, timestamp, tag o rami.

Query per timestamp

Per eseguire una query sui dati a partire da un timestamp specifico:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME TIMESTAMP AS OF '2026-02-26 01:21:00';

BigQuery 

SELECT * FROM `PROJECT_ID.CATALOG_ID.NAMESPACE.TABLE_NAME` FOR SYSTEM_TIME AS OF '2026-02-26 01:21:00';

Eseguire query per ID snapshot

Per eseguire una query sui dati a partire da un ID snapshot specifico:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;

Query per tag

Per creare un tag ed eseguire query sui dati a partire da quel tag:

Spark 

-- Create tag 'historical-snapshot'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE TAG 'historical-snapshot' AS OF VERSION 123456789012345;

-- Query by tag
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'historical-snapshot';

Query per filiale

Per creare un ramo ed eseguire query sui dati a partire da quel ramo:

Spark 

-- Create branch 'audit-branch'
ALTER TABLE NAMESPACE.TABLE_NAME CREATE BRANCH 'audit-branch' AS OF VERSION 123456789012345;

-- Query by branch
SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 'audit-branch';

Passaggi successivi