Usar o Lakehouse sem fronteiras

O Lakehouse para Apache Iceberg oferece suporte a consultas de dados remotos por meio de uma configuração de Lakehouse sem fronteiras. Depois de configurado, o sistema oferece suporte ao acesso aos dados usando 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 de consultas analíticas, é possível usar os dados federados para insights e governança orientados por IA:

  • Análise conversacional: crie agentes especializados com base nas suas fontes de dados exatas, incluindo tabelas entre nuvens, para analisar dados em nuvens a partir de 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, é possível criar agentes especializados com base nas suas fontes de dados, de projetos, conjuntos de dados e tabelas a visualizações, gráficos e funções definidas pelo usuário. Como os dados raramente ficam em um só lugar, a análise conversacional vai além das tabelas padrão do BigQuery para tabelas do Apache Iceberg gerenciadas pelo Lakehouse e fontes do Lakehouse sem fronteiras, como Databricks Unity, AWS Glue, SAP e Salesforce. Isso permite dividir silos de dados e analisar dados em nuvens a partir de uma única conversa.

Esta página mostra como consultar dados remotos depois de configurar um Lakehouse sem fronteiras.

Antes de começar

Antes de consultar os dados, conclua as seguintes etapas:

  1. Configure o Lakehouse sem fronteiras para AWS Glue, Databricks Unity Catalog, ou Snowflake.
  2. Verifique se há dados no catálogo remoto.

Funções exigidas

Para conseguir 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:

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

Consultar dados

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

Lakehouse processa a tradução de metadados e o acesso seguro a dados, o que permite tratar tabelas remotas do Apache Iceberg como se fossem locais para seu Google Cloud ambiente.

Consultar pelo 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 distribuição 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 Google Cloud projeto.
  • 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"

Consultar pelo 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 distribuição de credenciais ativada usando X-Iceberg-Access-Delegation=vended-credentials. O Spark vai usar as credenciais distribuídas de escopo de curta duração para se conectar ao S3 com segurança, sem precisar gerenciar credenciais separadas da AWS ou conectores do S3.

  1. 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 de rede. É necessário provisionar um Cloud Router e um 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.

  2. 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 desse arquivo 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.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,\
    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 gs:// do Cloud Storage para o arquivo de 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 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 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 data 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 da 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 do gerenciador de autenticação personalizado. Defina como org.apache.iceberg.gcp.auth.GoogleAuthManager para autenticação de fluxo 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 de portador ou 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 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 distribuição 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 Nenhum parâmetro de armazenamento adicional é necessário.

    Para o 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 no Snowflake.

A seguir