A partir de 20 de abril de 2026, o BigLake agora se chama Lakehouse. O metastore do BigLake agora é chamado de catálogo de ambientes de execução do Lakehouse. As APIs do Lakehouse, as bibliotecas de cliente, os comandos da CLI e os nomes do IAM permanecem inalterados e ainda fazem referência ao BigLake.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Sobre o endpoint do catálogo REST do Apache Iceberg

O Lakehouse sem fronteiras gerencia metadados pelo catálogo do 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 rigorosa. A configuração do catálogo determina os tipos de armazenamento compatíveis e os comportamentos de roteamento regional.

Recursos e compliance

O catálogo do ambiente 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 seguindo APIs abertas.

Formatos de tabela compatíveis

As tabelas do Apache Iceberg V2 (GA) e V3 (pré-lançamento) são compatíveis. As tabelas do Iceberg V1 não são compatíveis. Antes de usar as 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 a V2.

Conformidade com a API e operações REST

O catálogo do ambiente de execução do Lakehouse implementa a API REST do catálogo do Apache Iceberg, que é 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 REST Catalog 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 mostra 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 é respaldado por locais de armazenamento de warehouse designados (como um ou mais buckets do Cloud Storage) que armazenam os metadados e os arquivos de dados subjacentes.
Namespace	Um grupo 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.

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 (recomendado) ou de um único bucket.

As duas opções são compatíveis com a venda de credenciais.

Ao configurar mecanismos de consulta de cliente (como Spark ou Trino) para se conectar ao endpoint do catálogo REST do Apache Iceberg, especifique o caminho do warehouse com base no tipo de catálogo:

Catálogo de vários buckets: defina o caminho do warehouse como bl://projects/PROJECT_ID/catalogs/CATALOG_ID.
Catálogo de bucket único: defina o caminho do warehouse como gs://CLOUD_STORAGE_BUCKET_NAME.

Catálogo de vários buckets (recomendado)

Essa abordagem permite nomear o catálogo de forma independente de qualquer nome de bucket e configurar vários buckets para um único catálogo. Na API, isso corresponde à configuração CATALOG_TYPE_BIGLAKE.

Considerações:

Configuração do warehouse do cliente (bl://): ao configurar um cliente do Iceberg para se conectar a um catálogo de vários buckets, especifique o caminho do warehouse usando o formato de URI bl://: bl://projects/PROJECT_ID/catalogs/CATALOG_ID. O formato bl:// é usado exclusivamente durante a configuração do cliente para identificar o catálogo. Ao criar ou configurar o catálogo no Google Cloud, os locais de armazenamento (default_location e restricted_locations) são sempre especificados como caminhos do Cloud Storage (gs://).
Locais de armazenamento máximos: além de default_location, é possível especificar até 128 buckets ou subcaminhos do Cloud Storage em restricted_locations por catálogo.
Local padrão: forneça 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 será possível 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 opcional de restricted_locations 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, entre 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 não é recomendada, 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 terão um sufixo de string aleatório adicionado 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

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

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

Por exemplo, se você nomear o bucket como iceberg-bucket, o catálogo e o bucket vão compartilhar esse nome. Use esse nome ao 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. O uso da configuração legada de bucket único não é recomendado para 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.
- Projeto: bloqueado para o projeto do bucket (não há suporte para catálogos entre projetos).
- Região: derivada estritamente do local do bucket e não pode ser personalizada.
- Armazenamento: restringe o catálogo a um único bucket (sem locais restritos).
Configuração do warehouse do cliente (gs://): ao configurar um cliente do Iceberg para um catálogo de bucket único, especifique o caminho do bucket do Cloud Storage (gs://CLOUD_STORAGE_BUCKET_NAME) como o local do warehouse.
Restrição de um catálogo por bucket: para esse tipo de catálogo legado, só é possível 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 (recomendado): é possível fazer upgrade de um catálogo de bucket único para um catálogo de vários buckets (recomendado). O catálogo atualizado mantém o nome do bucket original. Depois disso, é possível 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 do ambiente de execução do Lakehouse é determinada pela região do bucket do Cloud Storage:

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

A região do catálogo mapeada 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 à birregião do bucket (como ASIA1 ou NAM4).
Multirregional: 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 estar alinhado com as 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 encaminha 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 do catálogo na 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 realizar um failover dinamicamente chamando FailoverCatalog. Para mais informações, consulte Criar um catálogo.

Para rotear solicitações diretamente para uma região específica para requisitos de residência e soberania de dados, use endpoints regionais (biglake.LOCATION.rep.googleapis.com). Para mais informações, consulte Endpoints regionais do Lakehouse.

Consultar catálogos do BigQuery

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

Projeto: o ID do projeto do Google Cloud que é proprietário do catálogo.
Catálogo: o nome do catálogo do ambiente 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

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.