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 estrita. 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 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 do ambiente 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 fornece 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 locais de armazenamento de warehouse designados (como um ou mais buckets do Cloud Storage) que armazenam 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 (recomendado) ou de um único bucket.

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

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

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

Catálogo de vários buckets (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:

Configuração do data 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 data 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://).
Número máximo de buckets: é possível especificar no máximo 15 buckets por catálogo.
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: permite 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

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 (gs://) especificado por você. Na API subjacente, 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. 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 da localização do bucket e não pode ser personalizada.
- Armazenamento: restringe seu catálogo a um único bucket (sem locais restritos).
Configuração do data 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 data warehouse.
Restrição de um catálogo por 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 (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 original do bucket. Depois disso, você pode associar vários buckets ao catálogo e configurar locais restritos.

Regiões do bucket e do 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 subjacente:

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 é derivada estritamente do bucket associado a ele 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 à região dupla 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 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 de 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 nessas 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.

Para encaminhar solicitações diretamente a uma região específica para atender aos 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, 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 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.