Desde 20 de abril de 2026, o BigLake agora é chamado de Lakehouse para Apache Iceberg. O metastore do BigLake agora é chamado de catálogo do ambiente de execução do Lakehouse. As APIs do data lakehouse, as bibliotecas de cliente, os comandos da CLI e os nomes do IAM permanecem inalterados e ainda fazem referência ao BigLake.

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Sobre o endpoint do catálogo REST do Apache Iceberg

O Lakehouse para Apache Iceberg gerencia metadados pelo catálogo de ambiente de execução do Lakehouse. Quando você usa o endpoint do catálogo REST do Apache Iceberg, o sistema organiza os dados em uma hierarquia de recursos estrita. A configuração do catálogo determina os tipos de armazenamento compatíveis, os comportamentos de roteamento regional e as opções de federação de consultas.

Recursos e compliance

O catálogo de ambientes de execução do Lakehouse foi criado para se integrar a mecanismos de consulta compatíveis com o Iceberg, oferecendo suporte a formatos de tabela padrão e obedecendo a APIs abertas.

Formatos de tabela compatíveis

As tabelas do Apache Iceberg V2 (GA) e V3 (prévia) são compatíveis. Não há suporte para tabelas do Iceberg V1. Antes de usar tabelas V1 com o endpoint do catálogo REST do Apache Iceberg, faça upgrade delas para uma versão compatível. Para mais informações, consulte Fazer upgrade de tabelas do Iceberg V1 para V2.

Conformidade da API e operações REST

O catálogo de ambientes de execução do Lakehouse implementa a API de catálogo REST do Apache Iceberg, um padrão aberto. Os mecanismos de consulta do cliente interagem com o catálogo usando APIs REST padrão. Para mais informações, consulte Como o Lakehouse implementa a API do catálogo REST do Apache Iceberg.

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. Cada catálogo é apoiado por um local de armazenamento de data warehouse designado (como um bucket do Cloud Storage ou um proxy de federação do BigQuery) que armazena os metadados e arquivos de dados subjacentes.
Namespace	Um agrupamento lógico usado para organizar tabelas em um catálogo. Ele funciona como bancos de dados, esquemas ou diretórios.
Tabela	As tabelas contêm definições de linhas e colunas que podem ser consultadas.

Catálogos e locais de armazenamento

A configuração de um catálogo determina como ele opera e se integra aos serviços do Google Cloud. É possível configurar um catálogo de vários buckets (bl://, recomendado) ou de um único bucket (gs://).

As duas opções oferecem suporte à venda de credenciais para controle de acesso refinado.

Catálogo de vários buckets (`bl://`) (recomendado)

Com essa abordagem, é possível nomear o catálogo de forma independente de qualquer nome de bucket e configurar vários buckets para um único catálogo. Na API subjacente, isso corresponde à configuração CATALOG_TYPE_BIGLAKE.

Considerações:

Local padrão: você fornece um caminho para um bucket (default_location) ou um subcaminho (como gs://my-bucket/path) para atuar como o local de armazenamento padrão. Todos os recursos do catálogo (namespaces e tabelas) precisam estar localizados no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não poderá hospedar namespaces ou tabelas em gs://my-bucket/another/path. Para namespaces criados sem um local especificado, o default_location é usado.
Locais restritos: também é possível fornecer uma configuração restricted_locations opcional para outros buckets ou caminhos em que namespaces e tabelas podem ser criados. Se você especificar um subcaminho (como gs://my-bucket/path), todos os recursos criados usando essa configuração precisarão estar nesse caminho. Por exemplo, gs://my-bucket/another/path não pode hospedar namespaces ou tabelas.
Requisitos do grupo de regiões geográficas: embora os buckets possam ser entre projetos e regiões e ter configurações diferentes (como região única, birregional ou multirregional), todos os locais do Cloud Storage no local padrão e nos locais restritos precisam estar no mesmo grupo de regiões geográficas (como EUA, Europa, Canadá ou Ásia). Por exemplo, não é possível configurar um bucket multirregional dos EUA com um bucket na Europa ou no Canadá.
Vários catálogos por bucket: é possível ter vários catálogos apontando para o mesmo bucket (por exemplo, usando locais padrão ou restritos diferentes). No entanto, essa configuração é altamente desencorajada porque pode levar a conflitos de metadados, substituições acidentais de dados ou problemas de segurança, como vazamento de permissões.
Namespaces: permitem especificar locais de namespace personalizados, desde que estejam em um caminho configurado nos locais padrão ou restritos. As tabelas criadas nesses catálogos têm um sufixo de string aleatório anexado automaticamente aos caminhos físicos para evitar conflitos (por exemplo, gs://{bucket_name}/{namespace_name}/{table_name}/{random_suffix}). Para mais informações, consulte Regras de segurança e gerenciamento de tabelas.

Catálogo de bucket único (`gs://`)

Essa é a abordagem legada em que o catálogo gerencia diretamente os metadados e arquivos de dados do Apache Iceberg em um único bucket do Cloud Storage especificado por você. Na API subjacente, isso corresponde à configuração CATALOG_TYPE_GCS_BUCKET.

Para catálogos de um único bucket, o nome do catálogo é definido como o nome do bucket.

Por exemplo, se você criou um bucket para armazenar seu catálogo e o nomeou como 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.lakehouse-catalog-id.quickstart_namespace.quickstart_table.

Considerações:

Limitações do tipo de catálogo legado. Não é recomendável usar a configuração legada de bucket único em novos projetos. Essa configuração tem várias limitações críticas:
- Nome do catálogo: bloqueado para o nome do bucket do Cloud Storage subjacente.
- Projeto: bloqueado para o projeto do bucket (catálogos entre projetos são indisponíveis).
- Região: derivada estritamente do local do bucket e não pode ser personalizada.
- Armazenamento: restringe seu catálogo a um único bucket (sem locais restritos).
Um catálogo por restrição de bucket: para esse tipo de catálogo legado, você só pode ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.
Fazer upgrade para um catálogo de vários buckets (bl://) (recomendado): você pode fazer upgrade de um catálogo de um único bucket (gs://) para um catálogo de vários buckets (bl://) (recomendado). O catálogo atualizado mantém o nome original do bucket. Depois disso, você pode associar vários buckets ao catálogo e configurar locais restritos.

Regiões de bucket e catálogo

A região de um endpoint de catálogo no catálogo de tempo de execução do Lakehouse é determinada pela região do bucket do Cloud Storage subjacente:

Catálogo de vários buckets (bl://) (recomendado): a região do catálogo é derivada do bucket configurado em default_location.
Bucket único (gs://): a região do catálogo é derivada estritamente do bucket associado a ele e não pode ser personalizada.

A região mapeada do catálogo varia de acordo com o tipo de região do bucket:

Região única: a região do catálogo corresponde exatamente à região do bucket.
Birregional: a região do catálogo corresponde à região birregional do bucket (como ASIA1 ou NAM4).
Multirregião: a região do catálogo é definida como um local regional específico no domínio geográfico da multirregião. Por padrão, isso pode não se alinhar com multirregiões comuns do BigQuery, como US e EU. Por exemplo, um bucket multirregional US é mapeado para us-central1 ou us-east4.

Quando o BigQuery executa uma consulta em tabelas nesses catálogos, ele direciona a consulta para a região principal do catálogo. Se você consultar tabelas 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 vai falhar.

Regiões principais para multirregiões

Para permitir que o BigQuery consulte as tabelas de catálogo da multirregião US ou EU, especifique US ou EU como a região principal ao criar o catálogo.

É possível especificar uma multirregião (US ou EU) como a região principal nas seguintes configurações:

Se o bucket default_location for:

Um bucket multirregional US ou EU.
Um bucket de região única dentro dessas multirregiões (como us-central1 ou europe-west4).
Um bucket birregional ou birregional personalizado nessas áreas (como NAM4 ou EUR4).

A réplica principal é definida quando você cria o catálogo, mas é possível fazer um failover dinâmico chamando FailoverCatalog. Para mais informações, consulte Criar um catálogo.

Como consultar catálogos do BigQuery

Ao consultar tabelas do catálogo de ambientes 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 Google Cloud que é proprietário do catálogo.
Catálogo: o nome do catálogo de ambientes 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

A seguir

Configurar o endpoint do catálogo REST do Apache Iceberg

Sobre o endpoint do catálogo REST do Apache Iceberg Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.