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 di 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 Google Cloud progetto.

  2. Abilita l'API BigLake.

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

  • Leggi i dati della tabella in modalità di distribuzione delle credenziali: BigLake Viewer (roles/biglake.viewer) - il progetto
  • Leggi 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 di 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, consulta Panoramica delle tabelle Apache Iceberg tables.

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.

Utilizzare le opzioni della tabella (anteprima)

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

  • Da BigQuery: BigQuery DML e la gestione automatica delle tabelle sono abilitate per impostazione predefinita.
  • Dai motori open source: per attivare la funzionalità, devi configurare in modo esplicito le proprietà della tabella. Per ulteriori informazioni, consulta Configurare le opzioni della tabella.

Quando esegui query sulle tabelle da BigQuery, puoi accedere sia alle tabelle Iceberg standard sia alle tabelle abilitate per le funzionalità gestite di BigQuery. Per istruzioni dettagliate, consulta Configurare le opzioni della tabella.

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 di 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 di runtime Lakehouse. Il progetto selezionato nella console viene fatturato per la query. Google Cloud Google Cloud

  • CATALOG_ID: l'ID del catalogo di 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 verrà utilizzato in un secondo momento quando esegui una 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.

Eseguire query utilizzando il viaggio nel tempo

Puoi eseguire query sui dati storici delle tabelle Iceberg di Lakehouse utilizzando il viaggio nel tempo. Puoi viaggiare nel tempo da BigQuery utilizzando la FOR SYSTEM_TIME AS OF clausola o da motori open source come Spark utilizzando ID snapshot , timestamp, tag o branch.

Eseguire query per timestamp

Per eseguire 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 query sui dati a partire da un ID snapshot specifico:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;

Eseguire 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';

Eseguire query per branch

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

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