Consultar uma tabela

A consulta de uma tabela lê dados dos arquivos do Cloud Storage usando os metadados gerenciados pelo catálogo de tempo de execução do Lakehouse.

É possível executar consultas de mecanismos de código aberto, como Spark e Trino, ou diretamente do BigQuery usando uma sintaxe de nome de tabela de quatro partes (sintaxe P.C.N.T ).

Antes de começar

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake, se ela ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  3. Configure o catálogo do ambiente de execução do Lakehouse com o endpoint do catálogo REST do Apache Iceberg.

Funções exigidas

Para ter as permissões necessárias para consultar uma tabela, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto e no bucket de armazenamento:

  • Ler dados da tabela no modo de venda de credenciais: Leitor do BigLake (roles/biglake.viewer): o projeto
  • Ler dados da tabela no modo sem fornecimento de credenciais:
    • Leitor do BigLake (roles/biglake.viewer): o projeto
    • Leitor de objetos do Storage (roles/storage.objectViewer): o bucket do Cloud Storage

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Recursos e suporte de tabelas

Ao usar tabelas no catálogo de tempo de execução do Lakehouse, é útil entender os diferentes tipos de tabelas e os recursos de ativação. Para saber mais sobre o uso específico de tabelas do Apache Iceberg, consulte Visão geral das tabelas do Apache Iceberg.

Tabelas do Iceberg compatíveis

Somente tabelas do Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. Não há suporte para tabelas do Iceberg V1. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas Iceberg V1 para V2.

Usar opções de tabela (prévia)

É possível ativar o uso de recursos gerenciados do BigQuery, como a linguagem de manipulação de dados (DML) do BigQuery e o gerenciamento automático de tabelas, configurando propriedades específicas da tabela. Esses recursos são ativados de maneiras diferentes, dependendo de onde a tabela é criada:

  • No BigQuery:a DML do BigQuery e o gerenciamento automático de tabelas são ativados por padrão.
  • De mecanismos de código aberto:para ativar, configure explicitamente as propriedades da tabela. Consulte Configurar opções de tabela para mais informações.

Ao consultar tabelas do BigQuery, é possível acessar tabelas Iceberg padrão e tabelas ativadas para recursos gerenciados do BigQuery. Consulte Configurar opções de tabela para instruções detalhadas.

Consultar uma tabela

Selecione todos os dados da tabela:

Spark 

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

Trino 

SELECT * FROM TABLE_NAME;

BigQuery

Para consultar tabelas do Apache Iceberg no catálogo de tempo de execução do Lakehouse no BigQuery, use o nome de tabela de quatro partes na consulta com o seguinte formato: PROJECT_NAME.CATALOG_ID.NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME.

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

Substitua os seguintes valores:

  • PROJECT_NAME: o projetoGoogle Cloud que tem o catálogo no catálogo de tempo de execução do Lakehouse. O projetoGoogle Cloud selecionado no console Google Cloud é cobrado pela consulta.

  • CATALOG_ID: o ID do catálogo de ambientes de execução do Lakehouse especificado quando o catálogo foi criado. Esse identificador é usado como o nome do catálogo em consultas do BigQuery.

    Esse identificador também é o nome do seu bucket do Cloud Storage.

    Por exemplo, se você criou um bucket para armazenar seu catálogo e o nomeou iceberg-bucket, tanto o nome do catálogo quanto o do bucket serão iceberg-bucket. Isso será usado mais tarde quando você consultar seu catálogo no BigQuery usando a sintaxe P.C.N.T. Por exemplo, my-project.catalog_id.quickstart_namespace.quickstart_table.

  • NAMESPACE_OR_SCHEMA_NAME: o namespace da tabela, se você estiver usando o Spark, ou o nome do esquema da tabela, se estiver usando o Trino.

  • TABLE_NAME: o nome da tabela.

Consultar usando a viagem no tempo

É possível consultar dados históricos das tabelas gerenciadas do Apache Iceberg usando a viagem no tempo. É possível viajar no tempo pelo BigQuery usando a cláusula FOR SYSTEM_TIME AS OF ou por mecanismos de código aberto, como o Spark, usando IDs de snapshots, carimbos de data/hora, tags ou ramificações.

Consultar por carimbo de data/hora

Para consultar dados de um carimbo de data/hora específico:

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

Consultar por ID do snapshot

Para consultar dados de um ID de snapshot específico:

Spark 

SELECT * FROM NAMESPACE.TABLE_NAME VERSION AS OF 10963874102873;

Consultar por tag

Para criar uma tag e consultar dados a partir dela:

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

Consultar por ramificação

Para criar uma ramificação e consultar dados dela:

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

A seguir