Consultar tabelas do BigQuery pelo endpoint do catálogo REST do Apache Iceberg

O Lakehouse oferece interoperabilidade com o BigQuery ao rotear solicitações pelo endpoint do catálogo REST do Apache Iceberg para o catálogo do BigQuery. Com esse recurso, é possível expor tabelas gerenciadas pelo BigQuery, por exemplo, tabelas gerenciadas do Iceberg, para 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 dedicado do Lakehouse 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 de armazenamento 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 DDL padrão do BigQuery, além de dar aos mecanismos de OSS externos acesso somente leitura para consultar essas tabelas pelo endpoint do catálogo REST.

Como funciona a consulta de tabelas do BigQuery pelo endpoint do catálogo REST

O roteamento de solicitações para o catálogo do BigQuery permite 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 do ambiente de execução do Lakehouse.

O fluxo de trabalho funciona da seguinte maneira:

  1. Criar 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 warehouse do BigQuery pelo catálogo do ambiente de execução do Lakehouse: usando a API REST do Apache Iceberg do catálogo do ambiente de execução do Lakehouse, você faz a federação em um warehouse especificado pelo formato de caminho do warehouse bq://projects/PROJECT_ID (ou pela versão regional, bq://projects/PROJECT_ID/locations/LOCATION). Isso permite acessar a tabela do BigQuery em mecanismos de computação, como o Apache Spark, usando a API REST Catalog do 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.

Considerações

  • Como o roteamento de solicitações para o catálogo do BigQuery não cria um recurso de catálogo dedicado do Lakehouse, outros conceitos e configurações no nível do catálogo, como a hierarquia de recursos, as regiões de bucket e catálogo e a estrutura de nomenclatura P.C.N.T de quatro partes, não se aplicam a esse método. Na API subjacente, isso corresponde à configuração CATALOG_TYPE_BIGQUERY. A delegação de acesso ao armazenamento (venda de credenciais) não é compatível com catálogos federados do BigQuery.

  • Expor tabelas do BigQuery pelo endpoint do catálogo REST é diferente do recurso de acesso a dados entre nuvens do Lakehouse sem fronteiras. Enquanto esse fluxo de trabalho expõe as tabelas do Google Cloud a mecanismos de OSS externos, o Lakehouse conecta o Google Cloud a catálogos externos remotos, como o Databricks Unity Catalog, para consultar dados armazenados em outros provedores de nuvem diretamente do BigQuery e de mecanismos de OSS sem migrar dados. Para mais informações sobre esse fluxo de trabalho, consulte Sobre o acesso a dados entre nuvens.

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

A exposição de tabelas do BigQuery pelo endpoint do catálogo REST é diferente dos fluxos de trabalho em que o catálogo do ambiente 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 do ambiente de execução do Lakehouse atua como um gateway de proxy. Quando o catálogo do ambiente 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.
  • Controle de acesso: as tabelas federadas usam as permissões do IAM do BigQuery e as 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.
  • Recursos 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 do ambiente 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, se ainda não tiver feito isso.

    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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

Funções exigidas

Para receber as permissões necessárias para consultar tabelas do BigQuery pelo endpoint do catálogo REST do Apache Iceberg, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Ler recursos do catálogo e consultar dados da tabela:
  • Realizar operações de linguagem de manipulação de dados (DML):
    • Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto
    • Administrador do Storage (roles/storage.admin) no bucket do Cloud Storage. Se você usa 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 o cliente para o data warehouse do BigQuery

Para se conectar ao warehouse do BigQuery, configure o cliente (como Apache Spark ou Trino) com o formato de warehouse bq://projects/PROJECT_ID no 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 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, crie um namespace para as tabelas.

Spark

Para criar um namespace no warehouse 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 o catálogo.
  • LOCATION: um local do BigQuery. O valor padrão é a multirregião US.

Trino

Para criar um esquema no warehouse 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 catálogo do Trino que usa 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 o 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 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