Configurar o catálogo REST do Lakehouse Iceberg

Para novos fluxos de trabalho, recomendamos usar o endpoint do catálogo REST do Apache Iceberg no catálogo do ambiente de execução do Lakehouse.

Esse endpoint atua como uma única fonte de verdade, permitindo a interoperabilidade perfeita entre os mecanismos de consulta. Ele permite que mecanismos como o Apache Spark descubram, leiam e gerenciem de forma consistente as tabelas do lakehouse do Google Cloud.

Essa abordagem é uma boa opção se você usa mecanismos de código aberto para acessar dados no Cloud Storage e precisa de interoperabilidade com outros mecanismos, incluindo o BigQuery. Ele oferece suporte a recursos como venda de credenciais para controle de acesso refinado e replicação entre regiões e recuperação de desastres.

Por outro lado, o endpoint do catálogo personalizado do Apache Iceberg para BigQuery é uma integração anterior. Embora os fluxos de trabalho atuais possam continuar usando o catálogo REST, ele oferece uma experiência mais padronizada e rica em recursos.

Antes de começar

Familiarize-se com o catálogo de ambientes de execução do Lakehouse e a visão geral do endpoint do catálogo REST do Iceberg antes de continuar.

  1. Verifique se o faturamento está ativado para o projeto do Google Cloud .

  2. Ative a API BigLake.

    Funções necessárias para ativar APIs

    Para ativar as APIs, é necessário ter o papel do IAM de administrador de uso do serviço (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

    Ativar a API

Funções exigidas

Para receber as permissões necessárias para usar o endpoint do catálogo REST do Apache Iceberg no catálogo de tempo de execução do Lakehouse, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Realize tarefas administrativas, como gerenciar o acesso de usuários ao catálogo, o acesso ao armazenamento e o modo de venda de credenciais do catálogo:
  • Ler dados da tabela no modo de venda de credenciais: Leitor do BigLake (roles/biglake.viewer) no projeto. Se você usar mecanismos de consulta, como o Serviço Gerenciado para Apache Spark ou o Dataflow, para ler dados da tabela, conceda essa função à conta de serviço usada para executar jobs nesse mecanismo.
  • Gravar dados da tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor) no projeto. Se você usar mecanismos de consulta, como o Serviço Gerenciado para Apache Spark, o Serviço Gerenciado para Apache Spark ou o Dataflow, para gravar dados de tabela, conceda essa função à conta de serviço usada para executar jobs nesse mecanismo.
  • Use a conta de serviço do catálogo do ambiente de execução do Lakehouse provisionada automaticamente no modo de venda de credenciais: Usuário de objetos do Storage (roles/storage.objectUser) no bucket do Cloud Storage de destino. Depois de criar o catálogo, conceda explicitamente o papel de usuário do objeto de armazenamento (roles/storage.objectUser) no bucket de armazenamento à conta de serviço do catálogo do ambiente de execução do Lakehouse provisionada automaticamente.
  • Ler recursos do catálogo e dados da tabela no modo sem venda de credenciais:
  • Gerenciar recursos do catálogo e gravar dados de tabela no modo sem venda de credenciais:
  • Realize operações da linguagem de manipulação de dados (DML) com a federação de catálogos do BigQuery:
    • Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto
    • Administrador do Storage (roles/storage.admin) no bucket do Cloud Storage. Se você usar mecanismos de consulta, como o Serviço gerenciado para Apache Spark, para realizar operações de DML, conceda esses papéis à conta de serviço usada para executar jobs nesse mecanismo.

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

Limitações

O endpoint do catálogo REST do Apache Iceberg está sujeito às seguintes limitações:

Limitações gerais

  • O Trino só é compatível com a federação de catálogos do BigQuery ao usar o serviço gerenciado para Apache Spark no Compute Engine 2.3 nas versões de imagem 2.3.16 e mais recentes.
  • Ao usar o modo de venda de credenciais, defina a propriedade io-impl como org.apache.iceberg.gcp.gcs.GCSFileIO. O padrão, org.apache.iceberg.hadoop.HadoopFileIO, não é compatível.

Limitações da tabela

  • As tabelas gerenciadas pelo endpoint do catálogo REST do Apache Iceberg não são compatíveis com o controle de acesso refinado (FGAC), como segurança em nível de linha e coluna.

Limitações de dados

  • Somente arquivos Parquet são aceitos. Para mais detalhes sobre como o BigQuery processa arquivos Parquet, consulte Carregar dados Parquet do Cloud Storage.
  • O tamanho do arquivo metadata.json do Iceberg é limitado a 1 MB. Para solicitar um aumento desse limite, entre em contato com a equipe da sua Conta do Google.

Limitações de consulta

  • Não é possível criar visualizações sobre tabelas do Apache Iceberg gerenciadas pelo endpoint do catálogo REST do Apache Iceberg no BigQuery.
  • Não é possível consultar tabelas de metadados do Apache Iceberg (como .snapshots ou .files) no BigQuery usando identificadores de nome de cinco partes. É possível consultar essas tabelas usando o Spark.

Configurar o endpoint do catálogo REST do Iceberg

Antes de configurar o catálogo, recomendamos ler a visão geral do endpoint do catálogo REST do Apache Iceberg para entender a hierarquia de recursos, os tipos de catálogo e a estrutura de nomenclatura.

Estas são as etapas gerais a seguir ao usar o endpoint do catálogo REST do Apache Iceberg no catálogo do ambiente de execução do Lakehouse:

  1. Com base na visão geral do endpoint do catálogo REST do Iceberg, escolha o local do data warehouse do catálogo (Cloud Storage ou BigQuery).
  2. Se você estiver usando um data warehouse do Cloud Storage gs://, crie um catálogo que aponte para o local do data warehouse.
  3. Configure seu aplicativo cliente para usar o endpoint do catálogo REST do Apache Iceberg.
  4. Crie um namespace ou esquema para organizar as tabelas.
  5. Crie e consulte tabelas usando o cliente configurado.

Criar um catálogo

É possível criar um catálogo que usa credenciais de usuário final ou o modo de venda de credenciais.

  • Com as credenciais do usuário final, o catálogo transmite a identidade do usuário final que está acessando o Cloud Storage para verificações de autorização.

  • A venda de credenciais é um mecanismo de delegação de acesso ao armazenamento que permite que os administradores do catálogo de tempo de execução do Lakehouse controlem as permissões diretamente nos recursos do catálogo de tempo de execução do Lakehouse, eliminando a necessidade de os usuários do catálogo terem acesso direto aos buckets do Cloud Storage. Ele permite que os administradores do Lakehouse do Google Cloud concedam permissões aos usuários em arquivos de dados específicos.

Considerações

Familiarize-se com os requisitos de local antes de criar um catálogo.

  • Quando você cria um namespace, ele usa automaticamente a mesma região do seu catálogo.

  • Se o catálogo usar um bucket multirregional e você quiser usá-lo com as multirregiões do BigQuery (US ou EU), exclua e recrie o catálogo para especificar o local principal.

Credenciais do usuário final

Console

  1. Abra a página Lakehouse no console do Google Cloud .

    Acessar o lakehouse

  2. Clique em Criar catálogo.

  3. No campo Selecionar um bucket do Cloud Storage, insira o nome do bucket que será usado com seu catálogo. Ou clique em Procurar para escolher um bucket ou criar um novo. Só é possível ter um catálogo por bucket do Cloud Storage.

  4. Em Authentication method, selecione End-user credentials.

  5. Clique em Criar.

gcloud

Use o comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Substitua:

  • CATALOG_NAME: um nome para o catálogo. Para tabelas do Apache Iceberg compatíveis com o catálogo do ambiente de execução do Lakehouse, esse nome geralmente corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST. Por exemplo, se o bucket for gs://bucket-id, o nome do catálogo poderá ser bucket-id. Esse nome também é usado como identificador do catálogo ao consultar essas tabelas no BigQuery.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • LOCATION: (opcional) a região principal do catálogo para garantir a interoperabilidade com o BigQuery. Para buckets do Cloud Storage na região dos EUA (por exemplo, US ou us-central1) ou da UE (por exemplo, EU ou europe-west4), especifique US ou EU, respectivamente, para garantir que o catálogo esteja acessível e disponível para consultas nas multirregiões correspondentes do BigQuery. Para mais informações, consulte Regiões de bucket e catálogo.

Modo de fornecimento de credenciais

Um administrador do catálogo ativa a venda de credenciais ao criar ou atualizar um catálogo. Como usuário do catálogo, você pode instruir o endpoint do catálogo REST do Apache Iceberg a retornar credenciais de armazenamento com escopo reduzido especificando a delegação de acesso ao configurar o endpoint do catálogo REST do Apache Iceberg.

A conta de serviço do catálogo do ambiente de execução do Lakehouse provisionada automaticamente exige a função explícita de usuário de objetos do Storage (roles/storage.objectUser) no bucket de destino do Cloud Storage. Por padrão, ele é criado com acesso somente para leitores. Sem essa função, as credenciais vendidas não terão escopo suficiente para realizar gravações de armazenamento. Se você usa ferramentas como gcloud ou Terraform, precisa conceder essa função manualmente.

Console

  1. No console do Google Cloud , abra a página Lakehouse.

    Acessar o lakehouse

  2. Clique em Criar catálogo. A página Criar catálogo é aberta.

  3. Em Selecionar um bucket do Cloud Storage, insira o nome do bucket que será usado com seu catálogo. Ou clique em Procurar para escolher em uma lista de buckets atuais ou criar um novo. Só é possível ter um catálogo por bucket do Cloud Storage.

  4. Em Método de autenticação, selecione Modo de fornecimento de credenciais.

  5. Clique em Criar.

    Seu catálogo é criado e a página Detalhes do catálogo é aberta.

  6. Em Método de autenticação, clique em Definir permissões do bucket.

  7. Na caixa de diálogo, clique em Confirmar.

    Isso verifica se a conta de serviço do catálogo tem o papel "Administrador de objetos do Storage" no bucket de armazenamento.

gcloud

Use o comando gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Substitua:

  • CATALOG_NAME: um nome para o catálogo. Esse nome geralmente corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST. Por exemplo, se o bucket for gs://bucket-id, o nome do catálogo poderá ser bucket-id. Esse nome também é usado como o identificador do catálogo ao consultar essas tabelas no BigQuery.
  • PROJECT_ID: o ID do projeto do Google Cloud .

  • LOCATION: (opcional) a região principal do catálogo para garantir a interoperabilidade com o BigQuery. Para buckets do Cloud Storage na região dos EUA (por exemplo, US ou us-central1) ou da UE (por exemplo, EU ou europe-west4), especifique US ou EU, respectivamente, para garantir que o catálogo esteja acessível e disponível para consultas nas multirregiões correspondentes do BigQuery. Para mais informações, consulte Regiões de bucket e catálogo.

    Depois de criar o catálogo, conceda explicitamente o papel Usuário de objetos do Storage (roles/storage.objectUser) no bucket de armazenamento à conta de serviço do catálogo do Lakehouse Runtime provisionada automaticamente.

Configurar aplicativo cliente

Depois de criar um catálogo, configure o aplicativo cliente para usá-lo. Esses exemplos mostram como configurar com ou sem a venda de credenciais.

Cluster

Para usar o Spark com o endpoint do catálogo REST do Apache Iceberg no Serviço Gerenciado para Apache Spark, use propriedades para simplificar a configuração ou configure a sessão manualmente.

Crie um cluster com a propriedade de catálogo:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Substitua:

  • CLUSTER_NAME: um nome para o cluster.
  • PROJECT_ID: o ID do projeto do Google Cloud .
  • REGION: a região do cluster do Serviço Gerenciado para Apache Spark.
  • DATAPROC_VERSION: a versão da imagem do Serviço Gerenciado para Apache Spark, por exemplo, 2.2.
  • CATALOG_NAME: um nome para o catálogo do Lakehouse a ser usado no Spark. Pode ser igual a CATALOG_ID.
  • CATALOG_ID: o ID do catálogo do Lakehouse que você criou.

Em seguida, crie uma sessão do Spark sem especificar parâmetros manuais do catálogo:

from pyspark.sql import SparkSession

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

Configuração manual

Se você não usar a propriedade do cluster, crie um cluster conforme descrito acima (sem a flag --properties) e configure a sessão do Spark manualmente:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .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}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

  • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API. Defina como v1beta se você precisar contornar um problema conhecido com a geração de linhagem de dados.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Use gs://CLOUD_STORAGE_BUCKET_NAME. Para usar a federação de catálogos do BigQuery, consulte Usar a federação de catálogos com o BigQuery.
  • PROJECT_ID: o projeto que recebe a cobrança pelo uso do endpoint do catálogo REST do Apache Iceberg, que pode ser diferente do projeto proprietário do bucket do Cloud Storage. Para detalhes sobre a configuração do projeto ao usar uma API REST, consulte Parâmetros do sistema.

Configurar com o modo de venda de credenciais

Para usar a venda de credenciais, você precisa usar um catálogo no modo de venda de credenciais e adicionar o cabeçalho X-Iceberg-Access-Delegation às solicitações de catálogo REST do Iceberg com um valor de vended-credentials. Para isso, adicione a seguinte linha ao builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemplo com venda de credenciais

O exemplo a seguir configura o mecanismo de consulta com a venda de credenciais:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_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}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Para mais informações, consulte a seção Cabeçalhos em RESTCatalog da documentação do Apache Iceberg.

Os clusters do Serviço Gerenciado para Apache Spark oferecem suporte a fluxos de autorização do Google para o Apache Iceberg nas seguintes versões:

  • Versões 2.2.65 e mais recentes da imagem do Serviço Gerenciado para Apache Spark no Compute Engine 2.2.
  • Versões de imagem 2.3 do Serviço Gerenciado para Apache Spark no Compute Engine 2.3.11 e mais recentes.

Sem servidor

Envie uma carga de trabalho em lote do PySpark para o Serviço Gerenciado para Apache Spark usando propriedades para simplificar a configuração (recomendado) ou especificando todos os parâmetros.

Envie um job em lote com a propriedade de catálogo:

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Configuração manual

Se você preferir especificar todas as propriedades manualmente, use a seguinte configuração:

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/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Substitua:

  • PYSPARK_FILE: o caminho do Cloud Storage gs:// para o arquivo do aplicativo PySpark.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • 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.2.
  • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
  • REST_API_VERSION: defina como v1 para a versão estável da API. Defina como v1beta se você precisar contornar um problema conhecido com a geração de linhagem de dados.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Use gs://CLOUD_STORAGE_BUCKET_NAME. Para usar a federação de catálogos do BigQuery, consulte Usar a federação de catálogos com o BigQuery.

Configurar com o modo de venda de credenciais

Para usar a venda de credenciais, use um catálogo no modo de venda de credenciais e adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações de endpoint do catálogo REST do Apache Iceberg com um valor de vended-credentials. Para isso, adicione a seguinte linha às configurações do Serviço Gerenciado para Apache Spark: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemplo com venda de credenciais

O exemplo a seguir configura o mecanismo de consulta com a venda de credenciais:

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/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

Para mais informações, consulte a seção Cabeçalhos em RESTCatalog da documentação do Apache Iceberg.

O Serviço Gerenciado para Apache Spark é compatível com fluxos de autorização do Google para o Apache Iceberg nas seguintes versões de ambiente de execução:

  • Tempos de execução do Serviço Gerenciado para Apache Spark 2.2 2.2.60 e versões mais recentes
  • Tempos de execução do Serviço Gerenciado para Apache Spark 2.3 2.3.10 e versões mais recentes

Trino

Para usar o Trino com o endpoint do catálogo REST do Apache Iceberg, crie um cluster do Serviço Gerenciado para Apache Spark com o componente do Trino e configure as propriedades do catálogo usando a flag gcloud dataproc clusters create --properties. O exemplo a seguir cria um catálogo do Trino chamado CATALOG_NAME:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.biglake.project-id=PROJECT_ID,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager"

Substitua:

  • CLUSTER_NAME: um nome para o cluster.
  • REGION: a região do cluster do Serviço Gerenciado para Apache Spark.
  • DATAPROC_VERSION: versão da imagem do Serviço Gerenciado para Apache Spark, por exemplo, 2.2.
  • NETWORK_ID: ID da rede do cluster. Para mais informações, consulte Configuração de rede do cluster do Serviço Gerenciado para Apache Spark.
  • CATALOG_NAME: o nome do seu catálogo do Trino usando o endpoint do catálogo REST do Apache Iceberg.
  • REST_API_VERSION: defina como v1 para a versão estável da API. Defina como v1beta se você precisar contornar um problema conhecido com a geração de linhagem de dados.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Use gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID: o ID do projeto do Google Cloud a ser usado para o catálogo de tempo de execução do Lakehouse.

Depois da criação do cluster, conecte-se à instância principal da VM e use a CLI do Trino:

trino --catalog=CATALOG_NAME

O Serviço Gerenciado para Apache Spark Trino é compatível com fluxos de autorização do Google para Apache Iceberg nas seguintes versões:

  • Versões do ambiente de execução 2.2 do Serviço Gerenciado para Apache Spark no Compute Engine 2.2.65 e mais recentes
  • Versões do ambiente de execução 2.3 do Serviço Gerenciado para Apache Spark no Compute Engine 2.3.11 e mais recentes
  • O Serviço Gerenciado para Apache Spark no Compute Engine 3.0 não é compatível.

Configurar com o modo de venda de credenciais

A venda de credenciais é compatível apenas com a versão 481 e mais recentes do Trino.

Apache Iceberg 1.10 ou mais recente

O Apache Iceberg 1.10 de código aberto e versões mais recentes têm suporte integrado para fluxos de autorização do Google em GoogleAuthManager. Confira abaixo um exemplo de como configurar o Spark para usar o catálogo de ambiente de execução do Lakehouse e o endpoint do catálogo REST do Apache Iceberg.

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .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}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

  • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API. Defina como v1beta se você precisar contornar um problema conhecido com a geração de linhagem de dados.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Use gs://CLOUD_STORAGE_BUCKET_NAME. Para usar a federação de catálogos do BigQuery, consulte Usar a federação de catálogos com o BigQuery.
  • PROJECT_ID: o projeto que recebe a cobrança pelo uso do endpoint do catálogo REST do Apache Iceberg, que pode ser diferente do projeto proprietário do bucket do Cloud Storage. Para detalhes sobre a configuração do projeto ao usar uma API REST, consulte Parâmetros do sistema.

Configurar com o modo de venda de credenciais

O exemplo anterior não usa a venda de credenciais. Para usar a venda de credenciais, use um catálogo no modo de venda de credenciais e adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações de endpoint do catálogo REST do Apache Iceberg com um valor de vended-credentials. Para isso, adicione a seguinte linha ao builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemplo com venda de credenciais

O exemplo a seguir configura o mecanismo de consulta com a venda de credenciais:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_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}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Para mais informações, consulte a seção Cabeçalhos em RESTCatalog da documentação do Apache Iceberg.

Versões anteriores do Apache Iceberg

Para versões de código aberto do Apache Iceberg anteriores à 1.10, é possível configurar a autenticação OAuth padrão configurando uma sessão com o seguinte:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

  • CATALOG_NAME: o nome do endpoint do catálogo REST do Apache Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API. Defina como v1beta se você precisar contornar um problema conhecido com a geração de linhagem de dados.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Use gs://CLOUD_STORAGE_BUCKET_NAME. Para usar a federação de catálogos do BigQuery, consulte Usar a federação de catálogos com o BigQuery.
  • PROJECT_ID: o projeto que recebe a cobrança pelo uso do endpoint do catálogo REST do Apache Iceberg, que pode ser diferente do projeto proprietário do bucket do Cloud Storage. Para detalhes sobre a configuração do projeto ao usar uma API REST, consulte Parâmetros do sistema.
  • TOKEN: seu token de autenticação, que é válido por uma hora. Por exemplo, um token gerado usando gcloud auth application-default print-access-token.

Configurar com o modo de venda de credenciais

O exemplo anterior não usa a venda de credenciais. Para usar a venda de credenciais, use um catálogo no modo de venda de credenciais e adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações de endpoint do catálogo REST do Apache Iceberg com um valor de vended-credentials. Para isso, adicione a seguinte linha ao builder SparkSession: 

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemplo com venda de credenciais

O exemplo a seguir configura o mecanismo de consulta com a venda de credenciais:

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Para mais informações, consulte a seção Cabeçalhos em RESTCatalog da documentação do Apache Iceberg.

Criar um namespace ou esquema

Depois de configurar o cliente, crie um namespace ou esquema para organizar suas tabelas. A sintaxe para criar um namespace ou esquema varia de acordo com o mecanismo de consulta. Os exemplos a seguir mostram como criá-los usando o Spark e o Trino.

Spark

Data warehouse do Cloud Storage

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
spark.sql("USE NAMESPACE_NAME;")

Substitua NAMESPACE_NAME por um nome para o namespace.

Trino

Data warehouse do Cloud Storage

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;
USE CATALOG_NAME.SCHEMA_NAME;

Substitua:

  • CATALOG_NAME: o nome do seu catálogo do Trino usando o endpoint do catálogo REST do Apache Iceberg.
  • SCHEMA_NAME: um nome para o esquema.

A seguir