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

O Lakehouse para Apache Iceberg oferece interoperabilidade com o BigQuery por um recurso conhecido como federação de catálogo do BigQuery. Com esse recurso, é possível expor tabelas gerenciadas pelo BigQuery, como tabelas gerenciadas pelo Iceberg, a mecanismos externos de código aberto (OSS, na sigla em inglês), como Apache Spark e 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 apenas como um gateway de proxy. Quando mecanismos externos se conectam usando o prefixo de 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 a DDL ou as APIs padrão do BigQuery, além de dar aos mecanismos OSS externos acesso somente leitura para consultar essas tabelas pelo endpoint do catálogo REST.

Formatos de tabela compatíveis

Somente tabelas do Apache Iceberg V2 são compatíveis. As tabelas do Iceberg V1 não são. Se você tiver tabelas do Iceberg V1 armazenadas no catálogo do BigQuery, faça upgrade para a V2 (por exemplo, executando ALTER TABLE catalog.schema.table SET TBLPROPERTIES ('format-version'='2'); ou usando operações de mecanismo semelhantes) antes de usá-las com a federação de catálogo do BigQuery.

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

Com a federação de catálogos do BigQuery, é possível expor tabelas do BigQuery, como tabelas gerenciadas do 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 do catálogo do BigQuery funciona da seguinte maneira:

  1. Crie uma tabela no catálogo do BigQuery: crie uma tabela gerenciada do 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 usando o catálogo de ambientes de execução do Lakehouse: com a API REST do Apache Iceberg do catálogo de ambientes de execução do Lakehouse, você faz a federação 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, usando a API Lakehouse para Apache Iceberg. Nessa configuração, você tem uma experiência somente leitura do Spark, mas uma experiência de leitura/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 tempo 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 do ambiente de execução do Lakehouse usa o endpoint do catálogo REST do Apache Iceberg, as tabelas usam ACLs do Lakehouse para Apache Iceberg.
  • Capacidades de leitura e gravação do mecanismo: as tabelas federadas oferecem 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 das APIs do BigQuery e de mecanismos externos, como o Spark.

Antes de começar

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

  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álogos no BigQuery, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Ler recursos do catálogo e consultar dados da tabela:
  • Realize operações da linguagem de manipulação de dados (DML) com a federação de catálogos do BigQuery:
    • Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto
    • Administrador do Storage (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 papéis personalizados ou outros papéis predefinidos.

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

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

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

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

Criar namespaces para tabelas federadas

Depois de configurar o cliente para a federação de catálogos do BigQuery, você pode criar um namespace para as tabelas federadas.

Spark

Para usar a federação de catálogos do BigQuery, inclua as cláusulas LOCATION e DBPROPERTIES:

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;")

Substitua:

  • NAMESPACE_NAME: um nome para o namespace.
  • BUCKET_NAME: o bucket do Cloud Storage que você está usando com seu catálogo.
  • LOCATION: um local do BigQuery. O valor padrão é a multirregião US.

Trino

Para usar a federação de catálogos do BigQuery, inclua as propriedades LOCATION e gcp-region:

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

Substitua:

  • CATALOG_NAME: o nome do seu catálogo do Trino usando o endpoint do catálogo REST do Apache Iceberg.
  • SCHEMA_NAME: um nome para o esquema.
  • BUCKET_NAME: o bucket do Cloud Storage que você está usando com seu catálogo.
  • LOCATION: um local do BigQuery. O valor padrão é a multirregião US.

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 precisar de um nome de quatro partes P.C.N.T):

SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

Substitua:

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

A seguir