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.

Consultar dados remotos

No Lakehouse sem fronteiras, uma conexão entre nuvens permite acessar dados remotos de plataformas externas sem mover arquivos entre ambientes de nuvem. Em seguida, é possível consultar as tabelas federadas no BigQuery, no Serviço Gerenciado para Apache Spark ou no Apache Spark de código aberto.

Além das consultas analíticas, é possível usar os dados federados para insights e governança baseados em IA:

Análise de conversação: crie agentes especializados com base nas suas fontes de dados, incluindo tabelas federadas, para analisar dados em várias nuvens em uma única conversa.
Knowledge Catalog: crie perfis de dados e gere insights em todas as suas fontes de dados federadas.

Para uma análise mais detalhada, é possível criar agentes de análise de conversação que usam projetos, conjuntos de dados, tabelas, visualizações, gráficos e funções definidas pelo usuário. Esses agentes funcionam em tabelas padrão do BigQuery, tabelas do Apache Iceberg gerenciadas pelo Lakehouse e fontes do Lakehouse, como Databricks Unity Catalog, AWS Glue, SAP BDC e Salesforce.

Antes de começar

Antes de consultar os dados, faça o seguinte:

Verifique se há dados no catálogo remoto.
Configure uma conexão entre nuvens para o AWS Glue, Databricks Unity Catalog, Snowflake Horizon Catalog, Workday Data Lake ou SAP Business Data Cloud.

Funções exigidas

Para receber as permissões necessárias para consultar dados federados, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

Consultar dados no BigQuery: Visualização de Dados do BigQuery (roles/bigquery.dataViewer)
Executar jobs do BigQuery: Usuário de jobs do BigQuery (roles/bigquery.jobUser)
Descobrir e ler metadados de tabelas em catálogos do Lakehouse: Leitor do BigLake (roles/biglake.viewer)

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 por meio de papéis personalizados ou de outros papéis predefinidos.

Consultar dados

Depois de configurar a federação, é possível consultar seus dados remotos usando SQL padrão no BigQuery ou no Apache Spark no Serviço Gerenciado para Apache Spark.

O Lakehouse lida com a tradução de metadados e o acesso seguro aos dados, permitindo que você trate as tabelas remotas do Apache Iceberg como se fossem locais no seu ambiente do Google Cloud .

Consultar no BigQuery

Para consultar tabelas federadas do Apache Iceberg, use o SQL padrão do BigQuery. O caminho da tabela segue uma estrutura de quatro partes: project.federated_catalog.namespace.table. A venda de credenciais, o roteamento de trânsito da CCI e o armazenamento em cache entre nuvens (quando ativado no catálogo) são processados automaticamente pelo Google Cloud.

SELECT
  user_id,
  action,
  COUNT(*) as total_actions
FROM `PROJECT_ID.FEDERATED_CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME`
WHERE event_date >= '2026-04-01'
GROUP BY 1, 2;

Substitua:

PROJECT_ID: o ID do projeto Google Cloud .
FEDERATED_CATALOG_NAME: o nome do catálogo federado.
NAMESPACE_NAME: o namespace no catálogo.
TABLE_NAME: o nome da tabela.
REGION: a região do Google Cloud . Por exemplo, us-east4.

Também é possível executar a consulta usando a ferramenta de linha de comando bq:

bq --location="REGION" --project_id="PROJECT_ID" query --use_legacy_sql=false \
  "SELECT * FROM \`PROJECT_ID.FEDERATED_CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME\` LIMIT 10"

Consultar o Serviço Gerenciado para Apache Spark

Envie uma carga de trabalho em lote do PySpark para o Serviço Gerenciado para Apache Spark com a venda de credenciais ativada usando X-Iceberg-Access-Delegation=vended-credentials. O Spark vai usar as credenciais de curta duração com escopo para se conectar ao S3 de forma segura, sem precisar gerenciar credenciais separadas da AWS ou conectores do S3.

Ativar a conectividade de saída para o Serviço Gerenciado para Apache Spark.

O Serviço Gerenciado para Apache Spark não pode se conectar ao AWS S3 com a configuração de rede padrão. É preciso provisionar um Cloud Router e o Cloud NAT.
```
gcloud compute routers create lakehouse-router \
  --network=NETWORK_NAME \
  --region=REGION

gcloud compute routers nats create lakehouse-nat \
  --router=lakehouse-router \
  --auto-allocate-nat-external-ips \
  --nat-all-subnet-ip-ranges \
  --region=REGION
```
Substitua:
- NETWORK_NAME: a rede para a carga de trabalho em lote do Serviço Gerenciado para Apache Spark (por exemplo, default).
- REGION: a região da carga de trabalho em lote do Serviço Gerenciado para Apache Spark.

Criar um arquivo de aplicativo do PySpark e executar o job do PySpark.

from pyspark.sql import SparkSession
spark = SparkSession.builder.appName("CATALOG_NAME").getOrCreate()

df = spark.table("CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME")
df.show(10, truncate=False)

Faça upload para o Cloud Storage em PYSPARK_FILE.

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=IO_IMPL,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Substitua:

NAMESPACE_NAME: o namespace no catálogo federado.
TABLE_NAME: o nome da tabela no catálogo federado.
CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog).
PYSPARK_FILE: o caminho do Cloud Storage gs:// para o arquivo do aplicativo PySpark.
REGION: a região da carga de trabalho em lote do Serviço Gerenciado para Apache Spark.
RUNTIME_VERSION: a versão do ambiente de execução do Serviço Gerenciado para Apache Spark, por exemplo, 2.3.
PROJECT_ID: o projeto que é faturado pelo uso do endpoint do catálogo REST do Apache Iceberg.
FEDERATED_CATALOG_NAME: o nome do catálogo federado.
IO_IMPL: a implementação de FileIO que corresponde ao armazenamento subjacente.

Parâmetros de configuração do Spark

A tabela a seguir lista os parâmetros comuns necessários para todas as conexões:

Parâmetro	Descrição
`spark.sql.defaultCatalog`	O nome do catálogo padrão (por exemplo, `CATALOG_NAME`).
`spark.sql.catalog.CATALOG_NAME`	A classe de implementação do catálogo. Defina como `org.apache.iceberg.spark.SparkCatalog`.
`spark.sql.catalog.CATALOG_NAME.type`	O tipo de back-end do catálogo. Defina como `rest` para o catálogo REST do Iceberg.
`spark.sql.catalog.CATALOG_NAME.uri`	O URI do endpoint do catálogo REST. Defina como `https://biglake.googleapis.com/iceberg/v1/restcatalog`.
`spark.sql.catalog.CATALOG_NAME.warehouse`	O caminho do local do warehouse para o catálogo federado. Defina como `bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME`.
`spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project`	O ID do projeto do Google Cloud usado para atribuição de faturamento e cota. Defina como `PROJECT_ID`.
`spark.sql.extensions`	As extensões de sessão do Spark para sintaxe e recursos do Iceberg SQL. Defina como `org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions`.

A tabela a seguir lista os parâmetros de autenticação:

Parâmetro	Descrição
`spark.sql.catalog.CATALOG_NAME.rest.auth.type`	A classe do gerenciador de autenticação personalizada. Defina como `org.apache.iceberg.gcp.auth.GoogleAuthManager` para autenticação de fluxo do OAuth.
`spark.sql.catalog.CATALOG_NAME.oauth2-server-uri`	O URI do endpoint do servidor de token OAuth2. Defina como `https://oauth2.googleapis.com/token` para autenticação de token de acesso pessoal (PAT).
`spark.sql.catalog.CATALOG_NAME.token`	O token do portador ou o token de acesso pessoal (PAT). Normalmente definido como `$(gcloud auth application-default print-access-token)` para autenticação PAT.

A tabela a seguir lista parâmetros exclusivos com base no seu provedor de armazenamento (IO_IMPL):

Armazenamento	`spark.sql.catalog.CATALOG_NAME.io-impl`	Observações
Amazon S3	`org.apache.iceberg.aws.s3.S3FileIO`	Requer venda de credenciais (`X-Iceberg-Access-Delegation=vended-credentials`), se ativada. Parâmetro adicional: `spark.sql.catalog.CATALOG_NAME.s3.region` (para uma lista de regiões, consulte Cotas e endpoints do Amazon S3).
Cloud Storage	`org.apache.iceberg.gcp.gcs.GCSFileIO`	Parâmetro adicional: `spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint`=`https://oauth2.googleapis.com/token`.
Armazenamento de blobs do Azure	`org.apache.iceberg.azure.adlsv2.ADLSFileIO`	Nenhum parâmetro de armazenamento adicional é necessário.

No Snowflake, podem ocorrer problemas ao consultar colunas STRING porque elas são otimizadas automaticamente para armazenamento. É possível resolver isso de duas maneiras:

Opção 1: desativar a vetorização no Spark: adicione as seguintes propriedades de configuração do Spark à flag --properties:
spark.sql.iceberg.vectorization.enabled=false
spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
Opção 2: mudar a política de serialização no Snowflake: mude a política de serialização de armazenamento para COMPATIBLE na tabela do Snowflake.

Monitorar o uso do cache e a economia de custos de saída

Quando você ativa o armazenamento em cache entre nuvens em um catálogo federado ou em uma conexão do BigQuery, o Lakehouse armazena em cache os blocos de arquivos recuperados localmente na região de execução de consultas do Google Cloud . As consultas subsequentes, incluindo consultas diferentes que segmentam os mesmos blocos de arquivos, são lidas diretamente do cache local, em vez de buscar novamente os arquivos da nuvem remota.

Para verificar as taxas de ocorrência em cache e medir a economia de custos de saída, inspecione os detalhes do job no console do BigQuery ou recupere as estatísticas do job de consulta JobStatistics2 usando a API BigQuery ou a ferramenta de linha de comando bq:

bq show --format=prettyjson --job=true JOB_ID

Substitua JOB_ID pelo ID do job de consulta do BigQuery.

Na saída JSON em statistics.query.objectStorageStats (ou object_storage_stats na API proto), as estatísticas do job retornam uma lista com uma entrada para cada provedor de nuvem acessado durante a execução. Cada entrada contém os seguintes campos:

cloudProvider (cloud_provider): o provedor de nuvem que hospeda o repositório de objetos (por exemplo, AWS ou AZURE).
cacheBytesRead (cache_bytes_read): o total de bytes lidos do cache local do Google Cloud , evitando uma leitura de repositório de objetos remotos.
objectStorageBytesRead (object_storage_bytes_read): o total de bytes lidos diretamente do repositório de objetos do provedor de nuvem.

Para mais informações sobre conceitos de armazenamento em cache e considerações sobre residência de dados, consulte Armazenamento em cache inteligente.