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

Depois de configurar o acesso a dados entre nuvens, é possível consultar dados remotos de várias fontes. Com esse recurso do Lakehouse sem fronteiras, é possível acessar dados usando o SQL padrão no BigQuery, a versão de código aberto do Apache Spark ou o Serviço gerenciado para Apache Spark. Além das consultas analíticas, você pode usar seus dados federados para insights e governança com tecnologia de IA:

Análise Conversacional: crie agentes especializados com base nas suas fontes de dados exatas, incluindo tabelas federadas, para analisar dados em várias nuvens em uma única conversa.
Dataplex Catalog: use os recursos do Knowledge Catalog para criação de perfil de dados e insights com fontes de dados federadas.

Para insights mais detalhados, você pode criar agentes especializados com base nas suas fontes de dados, desde projetos, conjuntos de dados e tabelas até visualizações, gráficos e funções definidas pelo usuário. Como seus dados raramente ficam em um só lugar, a análise de conversas vai além das tabelas padrão do BigQuery e alcança tabelas do Apache Iceberg gerenciadas pelo Lakehouse e fontes do Lakehouse, como Databricks Unity, AWS Glue, SAP e Salesforce. Isso permite eliminar silos de dados e analisar dados em várias nuvens em uma única conversa.

Nesta página, mostramos como consultar dados remotos depois de configurar o acesso a dados entre nuvens.

Antes de começar

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

Verifique se você tem dados no catálogo remoto.
Configure uma conexão entre nuvens para 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 projeto:

Consultar dados no BigQuery: Leitor de dados do BigQuery (roles/bigquery.dataViewer)
Executar jobs do BigQuery: Usuário de jobs do BigQuery (roles/bigquery.jobUser)
Descubra e leia 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 o SQL padrão no BigQuery ou no Apache Spark no Serviço Gerenciado para Apache Spark.

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

Consultar do 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. O armazenamento em cache, a venda de credenciais e o roteamento de trânsito da CCI são processados automaticamente.

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 Google Cloud região. 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"

Consulta do 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 usa as credenciais temporárias com escopo vendido para se conectar ao S3 com segurança, sem precisar gerenciar credenciais separadas da AWS ou conectores do S3.

Ative 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 da 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.

Crie um arquivo de aplicativo PySpark e execute 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 do FileIO que corresponde ao seu 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 na nuvem do Google usado para faturamento e atribuição de cota. Defina como `PROJECT_ID`.
`spark.sql.extensions`	As extensões de sessão do Spark para sintaxe e recursos do SQL do Iceberg. 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 gerenciadora 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. Definido 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 de 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`	Exige a 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 Endpoints e cotas do Amazon S3.
Google 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`	Não são necessários parâmetros de armazenamento adicionais.

No Snowflake, você pode encontrar problemas ao consultar colunas STRING porque elas são otimizadas automaticamente para armazenamento. É possível resolver esse problema 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.

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

O armazenamento em cache do Lakehouse é ativado automaticamente para todas as consultas entre nuvens. Quando uma consulta é executada, o Lakehouse armazena automaticamente em cache os blocos de dados localmente no armazenamento Google Cloud . Consultas subsequentes que têm como destino os mesmos blocos de dados são lidas diretamente do cache local, em vez de buscar os dados novamente na nuvem remota.

Para verificar as ocorrências 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 CLI bq:

bq show --format=prettyjson --j JOB_ID

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 remoto que hospeda o armazenamento de objetos (por exemplo, AWS ou AZURE).
cacheBytesRead (cache_bytes_read): o total de bytes lidos do cache Google Cloud local, evitando uma leitura remota do armazenamento de objetos.
objectStorageBytesRead (object_storage_bytes_read): o total de bytes lidos diretamente do armazenamento de objetos do provedor de nuvem remoto.

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

A seguir

Regiões e recursos disponíveis.