Consultar catálogos federados com o Spark e o catálogo do ambiente de execução do Lakehouse

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Depois de configurar o acesso aos dados entre nuvens no catálogo do ambiente de execução do Lakehouse, é possível consultar tabelas remotas do Iceberg no Serviço Gerenciado para Apache Spark sem migrar arquivos ou gerenciar credenciais de armazenamento em nuvem separadas.

O catálogo do ambiente de execução do Lakehouse processa a sincronização de metadados e o acesso seguro a dados por venda de credenciais. Quando o Spark consulta uma tabela federada, o catálogo do ambiente de execução do Lakehouse traduz os metadados do catálogo e emite credenciais de curta duração e com escopo para que o Spark leia dados do Amazon S3 ou do Cloud Storage, tratando as tabelas como se fossem locais para seu ambiente doGoogle Cloud .

Tipos de catálogos federados compatíveis

O Serviço Gerenciado para Apache Spark é compatível com a consulta dos seguintes tipos de catálogo federado pelo endpoint do catálogo REST do Iceberg do catálogo do ambiente de execução do Lakehouse:

Tipo de catálogo federado	Back-ends de armazenamento compatíveis	Guia de configuração no catálogo do ambiente de execução do Lakehouse
AWS Glue Data Catalog	Amazon S3 (s3://: catálogo de contas padrão da AWS ou bucket de tabela do Amazon S3)	Conectar-se ao AWS Glue
Databricks Unity Catalog	Locais externos do Amazon S3 (s3://) ou do Cloud Storage (gs://)	Conectar ao Databricks Unity Catalog
Catálogo do Snowflake Horizon	Amazon S3 (s3://) ou Cloud Storage (gs://)	Conectar-se ao catálogo do Snowflake Horizon

Para saber mais sobre os requisitos de prontidão do catálogo e as definições de parâmetros do Spark para cada provedor de armazenamento, consulte Consultar dados remotos no catálogo do ambiente de execução do Lakehouse e Parâmetros de configuração do Spark.

Antes de começar

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataproc, BigLake, and BigQuery APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that you have the permissions required to complete this guide.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataproc, BigLake, and BigQuery APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

1. Verifique se você tem tabelas do Iceberg no catálogo remoto.
2. Configure uma conexão entre nuvens e um catálogo federado no catálogo do ambiente de execução do Lakehouse para seu provedor de catálogo remoto:
   • AWS Glue Data Catalog
   • Databricks Unity Catalog
   • Catálogo do Snowflake Horizon

Papéis necessários do Identity and Access Management (IAM)

Alguns papéis do IAM são necessários para executar os exemplos nesta página. Dependendo das políticas da organização, esses papéis podem já ter sido concedidos. Para verificar as concessões de papéis, consulte Você precisa conceder papéis?. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Os papéis necessários dependem de como a carga de trabalho é executada. Os clusters do Serviço Gerenciado para Apache Spark e os tempos de execução sem servidor do Serviço Gerenciado para Apache Spark 2.3 e versões anteriores executam cargas de trabalho como uma conta de serviço. Os ambientes de execução sem servidor 3.0 e posteriores do Serviço Gerenciado para Apache Spark executam cargas de trabalho com suas credenciais de usuário final (EUC, na sigla em inglês) por padrão. Portanto, você concede papéis de acesso aos dados à sua conta de usuário, em vez de uma conta de serviço. Se você especificar uma conta de serviço personalizada para um ambiente de execução 3.0 ou mais recente, a carga de trabalho será executada com as credenciais da conta de serviço. Para mais informações, consulte Papéis de implantações sem servidor.

Papéis do usuário

Para receber as permissões necessárias para criar um cluster do Serviço Gerenciado para Apache Spark, enviar uma carga de trabalho em lote ou criar uma sessão interativa, peça ao administrador para conceder a você os seguintes papéis do IAM:

• Use um cluster ou um ambiente de execução sem servidor 2.3 ou anterior:
  • Editor do Dataproc (roles/dataproc.editor) no projeto
  • Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço padrão do Compute Engine ou em uma conta de serviço personalizada
• Use um ambiente de execução sem servidor 3.0 ou mais recente: Editor do Dataproc sem servidor (roles/dataproc.serverlessEditor) no projeto
• Ler tabelas federadas com credenciais de usuário final em um ambiente de execução sem servidor 3.0 ou posterior: Leitor do BigLake (roles/biglake.viewer) no projeto que contém o catálogo federado
• Use as credenciais da conta de serviço em um ambiente de execução sem servidor 3.0 ou posterior: Usuário da conta de serviço (roles/iam.serviceAccountUser) na conta de serviço personalizada

Papéis da conta de serviço

Conceda os seguintes papéis à conta de serviço que executa sua carga de trabalho. Os ambientes de execução sem servidor do Serviço Gerenciado para Apache Spark 3.0 e versões mais recentes só precisam desses papéis se a carga de trabalho for executada com credenciais da conta de serviço.

Para garantir que a conta de serviço padrão do Compute Engine ou uma conta de serviço personalizada tenha as permissões necessárias para executar jobs do Serviço Gerenciado para Apache Spark e ler tabelas federadas, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço padrão do Compute Engine ou a uma conta de serviço personalizada:

Importante:conceda esses papéis à conta de serviço padrão do Compute Engine ou a uma conta de serviço personalizada, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.

• Execute jobs do Serviço Gerenciado para Apache Spark em um cluster ou em um ambiente de execução sem servidor 2.3 ou anterior: Worker do Dataproc (roles/dataproc.worker) no projeto
• Execute jobs do Serviço Gerenciado para Apache Spark em um ambiente de execução sem servidor 3.0 ou posterior:
  • Nó do Dataproc sem servidor (roles/dataproc.serverlessNode) no projeto
  • Agente de serviço do nó do Dataproc Resource Manager (roles/dataprocrm.nodeServiceAgent) no projeto
• Descobrir e ler metadados de tabelas federadas durante a execução: Leitor do BigLake (roles/biglake.viewer) no projeto que contém o catálogo federado

Para garantir que o agente de serviço do Serviço Gerenciado para Apache Spark ([e-mail]) tenha as permissões necessárias para resolver a propriedade de configuração simplificada dataproc.lakehouse.catalog. ao criar um cluster, enviar uma carga de trabalho em lote ou criar uma sessão interativa, peça ao administrador para conceder o papel do IAM de Leitor do BigLake (roles/biglake.viewer) ao agente de serviço do Serviço Gerenciado para Apache Spark ([e-mail]) no projeto que contém o catálogo federado.

Importante:conceda esse papel ao agente de serviço do Serviço Gerenciado para Apache Spark ([e-mail]), não à sua conta de usuário. Se o papel não for concedido ao principal correto, poderão ocorrer erros de permissão.

Configurar a conectividade de rede de saída para o Amazon S3

Quando você consulta catálogos federados apoiados pelo Amazon S3, as cargas de trabalho em lote sem servidor e as sessões interativas do Serviço Gerenciado para Apache Spark, e os clusters do Serviço Gerenciado para Apache Spark com IP interno não podem se conectar aos endpoints do Amazon S3 com a configuração de rede padrão. Provisione um Cloud Router e o Cloud NAT na sua rede VPC de carga de trabalho para permitir o tráfego de saída para o Amazon S3:

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 VPC do cluster do Serviço Gerenciado para Apache Spark, da carga de trabalho em lote ou da sessão interativa, por exemplo, default.
• REGION: a região do Google Cloud cluster, da carga de trabalho em lote ou da sessão interativa do Serviço Gerenciado para Apache Spark.

Configurar o Serviço Gerenciado para Apache Spark e consultar tabelas federadas

É possível configurar um cluster do Serviço Gerenciado para Apache Spark, uma carga de trabalho em lote sem servidor ou uma sessão interativa para se conectar ao catálogo federado no catálogo do ambiente de execução do Lakehouse. Esses recursos do Serviço Gerenciado para Apache Spark são compatíveis com a propriedade de configuração dataproc.lakehouse.catalog.CATALOG_NAME simplificada (recomendada), que lê a definição do catálogo federado do catálogo do ambiente de execução do Lakehouse e gera as propriedades necessárias do catálogo REST do Iceberg do Spark, incluindo os cabeçalhos de armazenamento io-impl e de fornecimento de credenciais. A forma de cluster da propriedade adiciona o prefixo dataproc:.

A configuração simplificada e a manual usam a autorização do Google para o Iceberg (GoogleAuthManager), que exige uma das seguintes versões de imagem de cluster ou de ambiente de execução sem servidor:

• Clusters do Serviço Gerenciado para Apache Spark: versões de imagem 2.2.65 e mais recentes da versão 2.2 ou versões de imagem 2.3.11 e mais recentes da versão 2.3.
• Cargas de trabalho em lote sem servidor e sessões interativas do Serviço Gerenciado para Apache Spark: ambientes de execução 2.2.60 e mais recentes, 2.3.10 e mais recentes ou 3.0.

Para cargas de trabalho em lote sem servidor e sessões interativas, as funções necessárias dependem da versão do ambiente de execução. Os ambientes de execução 3.0 e mais recentes usam credenciais de usuário final por padrão. Para mais detalhes, consulte Papéis necessários do IAM e Papéis de implantações sem servidor.

Cluster

Crie um cluster do Serviço Gerenciado para Apache Spark com o componente opcional do Iceberg usando propriedades de configuração simplificadas (recomendado) ou especificando manualmente as propriedades do catálogo.

Configuração simplificada usando propriedades (recomendado)

Crie o cluster com a propriedade de catálogo federado:

gcloud dataproc clusters create CLUSTER_NAME \
  --project=PROJECT_ID \
  --region=REGION \
  --image-version=IMAGE_VERSION \
  --optional-components=ICEBERG,JUPYTER \
  --enable-component-gateway \
  --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,spark:spark.sql.defaultCatalog=CATALOG_NAME"

Substitua:

• CLUSTER_NAME: um nome para o cluster.
• PROJECT_ID: o ID do projeto doGoogle Cloud .
• REGION: a região do Google Cloud cluster, por exemplo, us-central1.
• IMAGE_VERSION: a versão da imagem do Serviço Gerenciado para Apache Spark. Por exemplo, 2.3-debian12. Para conferir as versões compatíveis, consulte os requisitos no início desta seção.
• CATALOG_NAME: um nome para o catálogo local do Spark, por exemplo, federated_catalog. Pode ser o mesmo que FEDERATED_CATALOG_NAME.
• FEDERATED_CATALOG_NAME: o ID do catálogo federado que você criou em Antes de começar.

Observação :é possível transmitir vários catálogos separados por vírgulas para a flag --properties. Cada propriedade do catálogo de clusters requer o prefixo dataproc:.

Como consultar o catálogo do Snowflake Horizon

Se você estiver consultando um catálogo do Snowflake Horizon, observe o seguinte:

• Armazenamento do Snowflake:a configuração simplificada é compatível com tabelas do Snowflake armazenadas no Amazon S3. Para tabelas do Snowflake armazenadas no Cloud Storage, use a configuração manual com io-impl definido como org.apache.iceberg.gcp.gcs.GCSFileIO.

• Colunas STRING do Snowflake:se você encontrar erros ao consultar colunas STRING do Snowflake em que a política de serialização de armazenamento da tabela no Snowflake não é COMPATIBLE, é possível mudar a política de serialização de armazenamento para COMPATIBLE no Snowflake ou desativar a vetorização do Parquet no Spark adicionando as seguintes propriedades à flag --properties:

  spark:spark.sql.iceberg.vectorization.enabled=false,spark:spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
      

No notebook do Jupyter ou no aplicativo PySpark, crie o SparkSession sem especificar as configurações do catálogo:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Substitua APP_NAME pelo nome do aplicativo do Spark.

Configuração manual

Se você não usar a propriedade de configuração simplificada, crie o cluster conforme descrito anteriormente nesta seção, sem transmitir a propriedade dataproc:dataproc.lakehouse.catalog. para a flag --properties e configure o SparkSession manualmente. Para uma lista de valores de parâmetros do provedor de armazenamento, consulte Parâmetros de configuração do Spark.

from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"

spark = SparkSession.builder.appName("APP_NAME") \
.config('spark.sql.defaultCatalog', catalog_name) \
.config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
.config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
.config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
.config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
.config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
.config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config(f'spark.sql.catalog.{catalog_name}.io-impl', 'IO_IMPL') \
.config(f'spark.sql.catalog.{catalog_name}.s3.client-factory-impl', 'org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

Substitua IO_IMPL pela implementação de FileIO para o armazenamento que contém suas tabelas:

• Tabelas no Amazon S3: org.apache.iceberg.aws.s3.S3FileIO
• Tabelas no Cloud Storage: org.apache.iceberg.gcp.gcs.GCSFileIO

A propriedade s3.client-factory-impl se aplica apenas a tabelas no Amazon S3. Omita essa linha para tabelas do Cloud Storage.

Sem servidor

Envie uma carga de trabalho em lote do PySpark para o Serviço Gerenciado para Apache Spark sem servidor usando propriedades de configuração simplificadas (recomendado) ou especificando manualmente as propriedades do catálogo.

Configuração simplificada usando propriedades (recomendado)

Transmita a propriedade do catálogo federado sem o prefixo dataproc: ao enviar a carga de trabalho em lote:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
  --project=PROJECT_ID \
  --region=REGION \
  --version=RUNTIME_VERSION \
  --properties="dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,spark.sql.defaultCatalog=CATALOG_NAME"

Substitua:

• PYSPARK_FILE: o caminho do Cloud Storage gs:// para o arquivo do aplicativo PySpark.
• PROJECT_ID: o ID do projeto doGoogle Cloud .
• REGION: a região da carga de trabalho em lote.
• RUNTIME_VERSION: a versão do ambiente de execução sem servidor do Serviço Gerenciado para Apache Spark, por exemplo, 3.0. Para conferir as versões compatíveis, consulte os requisitos na seção anterior. Os papéis do IAM necessários dependem da versão do ambiente de execução.
• CATALOG_NAME: um nome para o catálogo local do Spark, por exemplo, federated_catalog. Pode ser igual a FEDERATED_CATALOG_NAME.
• FEDERATED_CATALOG_NAME: o ID do catálogo federado que você criou em Antes de começar.

Observação: é possível transmitir vários catálogos separados por vírgulas para a flag --properties.

Como consultar o catálogo do Snowflake Horizon

Se você estiver consultando um catálogo do Snowflake Horizon, observe o seguinte:

• Armazenamento do Snowflake:a configuração simplificada é compatível com tabelas do Snowflake armazenadas no Amazon S3. Para tabelas do Snowflake armazenadas no Cloud Storage, use a configuração manual com io-impl definido como org.apache.iceberg.gcp.gcs.GCSFileIO.

• Colunas STRING do Snowflake:se você encontrar erros ao consultar colunas STRING do Snowflake em que a política de serialização de armazenamento da tabela no Snowflake não é COMPATIBLE, é possível mudar a política de serialização de armazenamento para COMPATIBLE no Snowflake ou desativar a vetorização do Parquet no Spark adicionando as seguintes propriedades à flag --properties:

  spark.sql.iceberg.vectorization.enabled=false,spark.sql.catalog.CATALOG_NAME.table-override.read.parquet.vectorization.enabled=false
      

No arquivo do aplicativo PySpark, crie o SparkSession sem especificar configurações de catálogo:

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Configuração manual

Se você não usar a propriedade de configuração simplificada, especifique as propriedades do catálogo com a flag --properties do comando gcloud dataproc batches submit. Para uma lista de valores de parâmetro do provedor de armazenamento, consulte Parâmetros de configuração do Spark.

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.header.X-Iceberg-Access-Delegation=vended-credentials,\
spark.sql.catalog.CATALOG_NAME.io-impl=IO_IMPL,\
spark.sql.catalog.CATALOG_NAME.s3.client-factory-impl=org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory,\
spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Substitua IO_IMPL pela implementação de FileIO para o armazenamento que contém suas tabelas:

• Tabelas no Amazon S3: org.apache.iceberg.aws.s3.S3FileIO
• Tabelas no Cloud Storage: org.apache.iceberg.gcp.gcs.GCSFileIO

A propriedade s3.client-factory-impl se aplica apenas a tabelas no Amazon S3. Omita essa propriedade para tabelas do Cloud Storage.

Sem servidor

Crie uma sessão interativa sem servidor do Serviço Gerenciado para Apache Spark em um notebook usando a API DataprocSparkSession com propriedades de configuração simplificadas (recomendado) ou especificando manualmente propriedades do catálogo.

Configuração simplificada usando propriedades (recomendado)

Em um notebook com o pacote dataproc-spark-connect instalado, como um notebook do BigQuery Studio ou da Vertex AI Workbench, transmita a propriedade do catálogo federado sem o prefixo dataproc: ao criar a sessão:

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
.dataprocSessionConfig(session_config) \
.config(f'dataproc.lakehouse.catalog.{catalog_name}', 'projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
.config('spark.sql.defaultCatalog', catalog_name) \
.getOrCreate()

Substitua:

• CATALOG_NAME: um nome para o catálogo local do Spark, por exemplo, federated_catalog. Pode ser igual a FEDERATED_CATALOG_NAME.
• RUNTIME_VERSION: a versão do ambiente de execução sem servidor do Serviço Gerenciado para Apache Spark, por exemplo, 3.0. Para ver as versões compatíveis, consulte os requisitos anteriormente nesta seção. Os papéis do IAM necessários dependem da versão do ambiente de execução.
• APP_NAME: o nome do aplicativo do Spark.
• PROJECT_ID: o ID do projeto do Google Cloud .
• FEDERATED_CATALOG_NAME: o ID do catálogo federado que você criou em Antes de começar.

Também é possível definir essas propriedades em um modelo de sessão.

Como consultar o catálogo do Snowflake Horizon

Se você estiver consultando um catálogo do Snowflake Horizon, observe o seguinte:

• Armazenamento do Snowflake:a configuração simplificada é compatível com tabelas do Snowflake armazenadas no Amazon S3. Para tabelas do Snowflake armazenadas no Cloud Storage, use a configuração manual com io-impl definido como org.apache.iceberg.gcp.gcs.GCSFileIO.

• Colunas do Snowflake STRING:se você encontrar erros ao consultar colunas do Snowflake STRING em que a política de serialização de armazenamento da tabela no Snowflake não é COMPATIBLE, mude a política para COMPATIBLE no Snowflake ou desative a vetorização do Parquet no Spark adicionando as seguintes chamadas .config() ao criador de sessões:

  .config('spark.sql.iceberg.vectorization.enabled', 'false') \
  .config(f'spark.sql.catalog.{catalog_name}.table-override.read.parquet.vectorization.enabled', 'false')
      

Configuração manual

Se você não usar a propriedade de configuração simplificada, especifique as propriedades do catálogo ao criar a sessão. Para uma lista de valores de parâmetro do provedor de armazenamento, consulte Parâmetros de configuração do Spark.

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

catalog_name = "CATALOG_NAME"

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
.dataprocSessionConfig(session_config) \
.config('spark.sql.defaultCatalog', catalog_name) \
.config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
.config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
.config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
.config(f'spark.sql.catalog.{catalog_name}.warehouse', 'bl://projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
.config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
.config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation', 'vended-credentials') \
.config(f'spark.sql.catalog.{catalog_name}.io-impl', 'IO_IMPL') \
.config(f'spark.sql.catalog.{catalog_name}.s3.client-factory-impl', 'org.apache.iceberg.aws.s3.DefaultS3FileIOAwsClientFactory') \
.config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
.getOrCreate()

Substitua RUNTIME_VERSION conforme descrito no exemplo de configuração simplificada nesta guia.

Substitua IO_IMPL pela implementação de FileIO para o armazenamento que contém suas tabelas:

• Tabelas no Amazon S3: org.apache.iceberg.aws.s3.S3FileIO
• Tabelas no Cloud Storage: org.apache.iceberg.gcp.gcs.GCSFileIO

A propriedade s3.client-factory-impl se aplica apenas a tabelas no Amazon S3. Omita essa linha para tabelas do Cloud Storage.

Consultar tabelas federadas

Depois de configurar a sessão do Spark, é possível consultar tabelas no catálogo federado usando o PySpark ou o Spark SQL.

Observação: a propriedade dataproc.lakehouse.catalog. registra o catálogo no Spark, mas não o define como o catálogo padrão. Os exemplos anteriores definem a propriedade do cluster spark.sql.defaultCatalog sem servidor ou spark:spark.sql.defaultCatalog, que permite usar nomes de tabela não qualificados. Se você omitir essas propriedades, será necessário qualificar os nomes das tabelas com o nome do catálogo, conforme mostrado nos exemplos a seguir.

1. Leia uma tabela federada usando a API DataFrame do PySpark:

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

   Substitua:

   • CATALOG_NAME: o nome do catálogo local do Spark. Se você definir spark.sql.defaultCatalog como CATALOG_NAME, poderá omitir esse prefixo.
   • NAMESPACE_NAME: o namespace (banco de dados ou esquema) no catálogo federado.
   • TABLE_NAME: o nome da tabela no catálogo federado.

2. Consulte a tabela federada usando o Spark SQL:

   spark.sql("""
       SELECT *
       FROM CATALOG_NAME.NAMESPACE_NAME.TABLE_NAME
       LIMIT 10
   """).show()

Mesclar ou materializar dados em catálogos federados e locais

Os catálogos federados são somente leitura. Para mesclar dados remotos entre nuvens com tabelas locais ou materializar resultados de consultas federadas no Cloud Storage, anexe seu catálogo federado e um catálogo de leitura e gravação no catálogo do ambiente de execução do Lakehouse usando propriedades dataproc.lakehouse.catalog. separadas por vírgulas:

Cluster

Exemplo de cluster do Serviço Gerenciado para Apache Spark:

--properties="dataproc:dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,dataproc:dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG=projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID,spark:spark.sql.defaultCatalog=LOCAL_SPARK_CATALOG"

Sem servidor

Exemplo de carga de trabalho em lote sem servidor do Serviço Gerenciado para Apache Spark:

--properties="dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG=projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME,dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG=projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID,spark.sql.defaultCatalog=LOCAL_SPARK_CATALOG"

Sem servidor

Exemplo de sessão interativa sem servidor do Serviço Gerenciado para Apache Spark:

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session

session_config = Session()
session_config.runtime_config.version = 'RUNTIME_VERSION'

spark = DataprocSparkSession.builder.appName("APP_NAME") \
  .dataprocSessionConfig(session_config) \
  .config('dataproc.lakehouse.catalog.FEDERATED_SPARK_CATALOG', 'projects/PROJECT_ID/catalogs/FEDERATED_CATALOG_NAME') \
  .config('dataproc.lakehouse.catalog.LOCAL_SPARK_CATALOG', 'projects/PROJECT_ID/catalogs/LOCAL_CATALOG_ID') \
  .config('spark.sql.defaultCatalog', 'LOCAL_SPARK_CATALOG') \
  .getOrCreate()

Substitua RUNTIME_VERSION conforme descrito no exemplo de sessão interativa no início desta página.

Depois de definir essas propriedades, você pode consultar o catálogo federado e gravar os resultados em uma tabela no catálogo do ambiente de execução do Lakehouse local.

O principal que executa sua carga de trabalho é a conta de serviço para clusters, ambientes de execução sem servidor 2.3 e anteriores e ambientes de execução sem servidor 3.0 e posteriores com credenciais da conta de serviço. Para ambientes de execução sem servidor 3.0 e posteriores com credenciais de usuário final (o padrão), o principal é sua conta de usuário.

Para garantir que o principal que executa sua carga de trabalho tenha as permissões necessárias para gravar dados de tabela no catálogo local, peça ao administrador para conceder os seguintes papéis do IAM ao principal que executa sua carga de trabalho:

• Gravar dados da tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor) no projeto que contém o catálogo local
• Gravar dados de tabela no modo sem fornecimento de credenciais:
  • Editor do BigLake (roles/biglake.editor) no projeto que contém o catálogo local
  • Usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets do Cloud Storage associados ao catálogo local

O exemplo a seguir cria uma tabela no catálogo local com base em uma tabela federada:

spark.sql("""
    CREATE TABLE IF NOT EXISTS LOCAL_SPARK_CATALOG.LOCAL_NAMESPACE.materialized_table
    USING iceberg
    AS SELECT *
    FROM FEDERATED_SPARK_CATALOG.REMOTE_NAMESPACE.REMOTE_TABLE
""")

A seguir

• Criar um lakehouse com o Spark e o catálogo do ambiente de execução do Lakehouse.
• Saiba mais sobre como consultar dados remotos no catálogo do ambiente de execução do Lakehouse.
• Leia Sobre o acesso a dados entre nuvens.
• Saiba mais sobre o modo de venda de credenciais.