Conceitos de endpoint do catálogo REST do Apache Iceberg

O catálogo de execução do Lakehouse oferece gerenciamento centralizado de metadados para o Google Cloud Lakehouse. Este documento descreve os conceitos básicos do catálogo de execução do Lakehouse, com foco no endpoint do catálogo REST do Apache Iceberg , na hierarquia de recursos e em outros tipos de catálogo compatíveis.

Hierarquia de recursos

O endpoint do catálogo REST do Apache Iceberg usa uma hierarquia de recursos para organizar seus dados. A tabela a seguir oferece uma visão geral desses recursos:

Recurso Descrição
Catálogo O contêiner de nível superior, um catálogo, permite organizar namespaces e tabelas em grupos lógicos, dividindo-os em diferentes catálogos.
Namespace Um agrupamento lógico usado para organizar tabelas em um catálogo, que funciona como bancos de dados, esquemas ou diretórios.
Tabela As tabelas contêm definições de linhas e colunas que podem ser consultadas.

Tipos de catálogo compatíveis

Ao configurar o cliente, você especifica um local do warehouse. Essa escolha determina como o catálogo opera e se integra a outros Google Cloud serviços. A tabela a seguir descreve os tipos de catálogo compatíveis:

Tipo de catálogo Descrição
Bucket do Cloud Storage Todos os dados em um catálogo são armazenados em um único bucket do Cloud Storage; para dados compartilhados em vários buckets, são necessários vários catálogos.
Federação de catálogo do BigQuery Permite usar o endpoint do catálogo REST do Apache Iceberg para gerenciar e consultar tabelas visíveis ao BigQuery. Para mais informações, consulte Federação de catálogo com o BigQuery.

Detalhes do warehouse

Recomendado

  • Warehouse de bucket do Cloud Storage (gs://): essa é a abordagem padrão em que o catálogo gerencia diretamente os metadados e arquivos de dados do Apache Iceberg em um bucket do Cloud Storage especificado. Essa opção oferece controle direto sobre o layout dos dados e oferece suporte à venda de credenciais para controle de acesso refinado. Isso permite criar e gerenciar tabelas de catálogo REST do Lakehouse Iceberg.

    Por exemplo, se você criou o bucket para armazenar o catálogo e o nomeou como iceberg-bucket, o nome do catálogo e do bucket serão iceberg-bucket. Isso será usado mais tarde ao consultar o catálogo no BigQuery, usando a sintaxe P.C.N.T. Por exemplo, my-project.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Alternativa

  • Federação de catálogo do BigQuery (bq://): essa abordagem permite usar o endpoint do catálogo REST do Apache Iceberg para gerenciar e consultar tabelas visíveis ao BigQuery, sem precisar criar um recurso de catálogo. Para mais informações, consulte Federação de catálogo com o BigQuery.

Regiões de bucket e catálogo

Para warehouses de bucket do Cloud Storage no catálogo de execução do Lakehouse, o sistema seleciona a região do catálogo para corresponder à região do bucket subjacente:

  • Buckets de região única: a região do catálogo corresponde exatamente à região do bucket.

  • Buckets birregionais: incluem regiões duplas predefinidas e definidas pelo usuário, como ASIA1 e NAM4. A região do catálogo corresponde às regiões duplas.

  • Buckets multirregionais: o sistema seleciona locais regionais para o catálogo no domínio geográfico da multirregião. Por padrão, esses locais podem não corresponder a locais comuns do BigQuery, como US e EU. Em vez disso, eles são locais regionais no domínio geográfico (por exemplo, us-central1 e us-east4 para um bucket multirregional US).

Quando o BigQuery executa uma consulta em tabelas nesses catálogos, ele a encaminha para a região principal do catálogo. Se você executar uma consulta em uma região virtual específica (como US ou EU) e os metadados do catálogo não estiverem presentes nesse local, a consulta poderá falhar.

Especificar regiões principais para multirregiões dos EUA e da UE

Para catálogos que usam um bucket multirregional US ou EU, é possível especificar a região principal ao criar o catálogo para garantir que o BigQuery possa acessá-lo nas regiões correspondentes.

  • Multirregião da UE do Cloud Storage: especifique EU ou europe-west4.
  • Multirregião dos EUA do Cloud Storage: especifique US ou us-central1.

O sistema seleciona uma réplica principal de um catálogo quando você a cria, mas é possível atualizá-la dinamicamente chamando FailoverCatalog. Para mais informações sobre como definir locais principais, consulte Usar o endpoint do catálogo REST do Apache Iceberg.

Como consultar catálogos

Ao consultar tabelas de catálogo de execução do Lakehouse no BigQuery, você usa uma estrutura de nomenclatura de quatro partes, geralmente chamada de P.C.N.T:

  • Projeto: o ID do projeto que é proprietário do catálogo. Google Cloud
  • Catálogo: o nome do catálogo de execução do Lakehouse.
  • Namespace: o namespace do Apache Iceberg (equivalente a um conjunto de dados do BigQuery).
  • Tabela: o nome da tabela.

Por exemplo, my-project.lakehouse-catalog-id.my-namespace.my-table.

Federação de catálogo com o BigQuery

É possível usar a interface do endpoint do catálogo REST do Apache Iceberg para gerenciar e consultar tabelas visíveis ao BigQuery.

Os catálogos de federação do BigQuery não exigem que você crie um recurso de catálogo. Eles podem ser usados em qualquer projeto que tenha a API BigQuery ativada. Isso permite:

Como esses recursos são gerenciados pelo BigQuery, você precisa ter as permissões necessárias aplicáveis. A venda de credenciais não é compatível com catálogos federados.

Para ativar a federação, configure o cliente com o bq://projects/PROJECT_ID formato de warehouse no campo WAREHOUSE_PATH nos exemplos de configuração do cliente em Usar o endpoint do catálogo REST do Apache Iceberg. 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.

A seguir