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 di 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 hai già questa autorizzazione tramite il ruolo Proprietario (roles/owner). In caso contrario, puoi ottenere questa autorizzazione tramite il ruolo Amministratore Service Usage (roles/serviceusage.serviceUsageAdmin). Scopri come concedere i ruoli.

    Abilitare l'API

  3. Configura il catalogo di 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: BigLake Viewer (roles/biglake.viewer) - il progetto
  • Leggi i dati della tabella in modalità di distribuzione non 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 di Lakehouse, è utile comprendere i diversi tipi di tabelle e le relative funzionalità di attivazione. Per scoprire di più sull'utilizzo specifico delle tabelle Apache Iceberg, 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 Esegui l'upgrade delle tabelle Iceberg V1 alla versione V2.

Utilizza le opzioni della tabella (anteprima)

Puoi attivare l'utilizzo delle funzionalità gestite di BigQuery, come il linguaggio di manipolazione dei dati (DML) 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 l'opzione, devi configurare esplicitamente le proprietà della tabella. Per saperne di più, consulta Configura le opzioni della tabella.

Quando esegui query sulle tabelle da BigQuery, puoi accedere alle tabelle Iceberg standard e alle tabelle abilitate per le funzionalità gestite di BigQuery. Per istruzioni dettagliate, consulta Configura 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 progettoGoogle Cloud proprietario del catalogo nel catalogo di runtime Lakehouse. Il progettoGoogle Cloud selezionato nella console Google Cloud viene fatturato per la query.

  • 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 tuo bucket Cloud Storage.

    Ad esempio, se hai creato il bucket per archiviare il catalogo e lo hai chiamato iceberg-bucket, sia il nome del catalogo sia quello del bucket sono iceberg-bucket. Questo 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 il viaggio nel tempo

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

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

Esegui 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;

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 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