Consultar o BigQuery usando a federação de catálogos

O Lakehouse para Apache Iceberg oferece interoperabilidade com o BigQuery por meio de um recurso conhecido como federação de catálogo do BigQuery. Esse recurso permite expor tabelas gerenciadas pelo BigQuery, por exemplo, tabelas gerenciadas pelo Iceberg, a mecanismos de código aberto (OSS) externos, como o Apache Spark e o Trino.

Em vez de criar um contêiner de catálogo do Lakehouse dedicado para armazenar metadados, o endpoint do catálogo REST do Apache Iceberg atua puramente como um gateway de proxy. Quando mecanismos externos se conectam usando o prefixo do data warehouse bq://, o gateway encaminha as solicitações de catálogo diretamente para o catálogo interno do BigQuery. Isso permite criar e gerenciar tabelas diretamente no BigQuery usando APIs ou DDLs padrão do BigQuery, ao mesmo tempo em que oferece aos mecanismos de OSS externos acesso somente leitura para consultar essas tabelas pelo endpoint do catálogo REST.

Como funciona a federação de catálogo do BigQuery

A federação de catálogo do BigQuery permite expor tabelas do BigQuery, como tabelas gerenciadas pelo Iceberg e tabelas do metastore do BigQuery, pelo endpoint do catálogo REST do Apache Iceberg do catálogo de ambientes de execução do Lakehouse.

O fluxo de federação de catálogo do BigQuery funciona da seguinte maneira:

1. Criar uma tabela no catálogo do BigQuery: você cria uma tabela gerenciada pelo Iceberg no BigQuery usando instruções DDL. Essa tabela existe no catálogo do BigQuery, é regida por listas de controle de acesso (ACLs) do BigQuery e funciona como um recurso REST do BigQuery.
2. Federar no data warehouse do BigQuery pelo catálogo de ambientes de execução do Lakehouse: usando a API REST do Apache Iceberg do catálogo de ambientes de execução do Lakehouse, você federa em um data warehouse especificado pelo formato de caminho do data warehouse bq://projects/PROJECT_ID (ou a versão regional, bq://projects/PROJECT_ID/locations/LOCATION). Isso permite acessar a tabela do BigQuery de mecanismos de computação como o Apache Spark, pela API Lakehouse para Apache Iceberg. Nessa configuração, você tem uma experiência somente leitura do Spark, mas uma experiência de leitura e gravação do BigQuery.

Comparação com tabelas gerenciadas pelo endpoint do catálogo REST do Apache Iceberg

A federação de catálogo do BigQuery difere dos fluxos de trabalho em que o catálogo de ambientes de execução do Lakehouse usa o endpoint do catálogo REST do Apache Iceberg das seguintes maneiras:

• Gerenciamento de recursos e armazenamento de catálogo: as tabelas federadas residem no catálogo do BigQuery como recursos REST do BigQuery, e o catálogo de ambientes de execução do Lakehouse atua como um gateway de proxy. Quando o catálogo de ambientes de execução do Lakehouse usa o endpoint do catálogo REST do Apache Iceberg, as tabelas são armazenadas diretamente no catálogo como recursos REST do Lakehouse para Apache Iceberg.
• Controle de acesso: as tabelas federadas usam permissões do IAM do BigQuery e listas de controle de acesso (ACLs). Quando o catálogo de ambientes de execução do Lakehouse usa o endpoint do catálogo REST do Apache Iceberg, as tabelas usam ACLs do Lakehouse para Apache Iceberg.
• Recursos de leitura e gravação do mecanismo: as tabelas federadas fornecem acesso de leitura e gravação pelo BigQuery, mas acesso somente leitura de mecanismos externos, como o Spark. Quando o catálogo de ambientes de execução do Lakehouse usa o endpoint do catálogo REST do Apache Iceberg, as tabelas oferecem suporte a operações de leitura e gravação de APIs do BigQuery e mecanismos externos, como o Spark.

Antes de começar

• Somente tabelas do Apache Iceberg V2 (GA) e V3 (visualização pública) são aceitas. As tabelas do Iceberg V1 não são aceitas. Para fazer upgrade das tabelas V1 atuais, consulte Fazer upgrade das tabelas do Iceberg V1 para V2.

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

2. Ative a API BigLake.

   Funções necessárias para ativar APIs

   Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

   Ativar a API

Funções exigidas

Para receber as permissões necessárias para usar a federação de catálogo no BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Ler recursos de catálogo e consultar dados da tabela:
  • Leitor do BigLake (roles/biglake.viewer) no projeto
  • Leitor de objetos do Storage (roles/storage.objectViewer) no bucket do Cloud Storage
• Realizar operações de linguagem de manipulação de dados (DML) com a federação de catálogo do BigQuery:
  • Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto
  • Administrador de armazenamento (roles/storage.admin) no bucket do Cloud Storage. Se você usar mecanismos de consulta, como o Serviço Gerenciado para Apache Spark, para realizar operações de DML, conceda esses papéis à conta de serviço usada para executar jobs nesse mecanismo.

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 personalizados papéis ou outros predefinidos papéis.

Configurar a federação de catálogo do BigQuery

Para ativar a federação de catálogo do BigQuery, configure o cliente (como o Apache Spark ou o Trino) com o bq://projects/PROJECT_ID formato de data warehouse em o campo WAREHOUSE_PATH nos exemplos de configuração do cliente em Configurar o aplicativo cliente.

Também é possível incluir um local do BigQuery para restringir solicitações futuras a um único local usando o bq://projects/PROJECT_ID/locations/LOCATION formato.

Como esses recursos são gerenciados pelo BigQuery, é necessário ter as permissões necessárias aplicáveis.

Criar namespaces para tabelas federadas

Depois de configurar o cliente para a federação de catálogo do BigQuery, é possível criar um namespace para as tabelas federadas.

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

Consultar tabelas federadas no BigQuery

As tabelas criadas em um catálogo federado ficam visíveis no BigQuery e podem ser consultadas diretamente usando o SQL padrão do BigQuery (sem a necessidade de um nome P.C.N.T de quatro partes):

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

Substitua:

• NAMESPACE_NAME: o nome do namespace.
• TABLE_NAME: o nome da tabela.

A seguir

• Saiba como gerenciar catálogos no Google Cloud console.
• Saiba mais sobre as tabelas do Apache Iceberg com suporte do catálogo de ambientes de execução do Lakehouse.