Usar o metastore do BigLake com o catálogo REST do Iceberg

Pré-lançamento

Este recurso está sujeitos 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. Você encontra mais detalhes nas descrições das fases de lançamento.

Observação: para pedir feedback ou suporte sobre esse recurso, envie um e-mail para [e-mail].

O catálogo REST gerenciado do Apache Iceberg no metastore do BigLake cria interoperabilidade entre todos os mecanismos de consulta, oferecendo uma única fonte de verdade para todos os dados do Iceberg. Ele permite que mecanismos de consulta, como o Apache Spark, descubram, leiam metadados e gerenciem tabelas do Iceberg de maneira consistente.

As tabelas do Iceberg usadas com o catálogo REST do Iceberg são chamadas de tabelas do BigLake para Apache Iceberg (versão prévia). São tabelas do Iceberg criadas com mecanismos de código aberto e armazenadas no Cloud Storage. Eles podem ser lidos por mecanismos de código aberto ou pelo BigQuery. As gravações são compatíveis apenas com mecanismos de código aberto. Neste documento, nos referimos a essas tabelas como tabelas do BigLake Iceberg.

Antes de começar

1. Verify that billing is enabled for your Google Cloud project.

   Saiba como verificar se o faturamento está ativado em um projeto.

2. Enable the BigLake API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

3. Opcional: peça a um administrador para configurar a venda de credenciais pela primeira vez.
4. Opcional: entenda como o BigLake Metastore funciona e por que você deve usá-lo.

Funções exigidas

Para receber as permissões necessárias para usar o catálogo REST do Iceberg no metastore do BigLake, 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 credencial do catálogo:
  • Administrador do BigLake (roles/biglake.admin) no projeto
  • Administrador de armazenamento (roles/storage.admin) no bucket do Cloud Storage
• Ler dados da tabela no modo de venda de credenciais: Leitor do BigLake (roles/biglake.viewer) no projeto
• Gravar dados da tabela no modo de venda de credenciais: Editor do BigLake (roles/biglake.editor) no projeto
• Ler recursos do catálogo e dados da tabela no modo sem venda de credenciais:
  • Leitor do BigLake (roles/biglake.viewer) no projeto
  • Leitor de objetos do Storage (roles/storage.objectViewer) no bucket do Cloud Storage
• Gerenciar recursos do catálogo e gravar dados de tabelas no modo sem venda de credenciais:
  • Editor do BigLake (roles/biglake.editor) no projeto
  • Usuário de objetos do Storage (roles/storage.objectUser) no bucket do Cloud Storage

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.

Configurar o modo de fornecimento de credenciais

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

Um administrador do catálogo ativa a venda de credenciais no cliente do catálogo REST do Iceberg.

Como usuário do catálogo, você pode instruir o catálogo REST do Iceberg a retornar credenciais de armazenamento com escopo reduzido especificando a delegação de acesso, que faz parte da especificação da API REST do catálogo do Iceberg. Para mais informações, consulte Configurar um mecanismo de consulta com o catálogo REST do Iceberg.

Para inicializar o catálogo e ativar o modo de fornecimento de credenciais, siga estas etapas.

1. Inicialize o catálogo com o seguinte comando:

   curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

   Substitua:

   • PROJECT_ID: o ID do seu projeto Google Cloud .
   • CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena a tabela do Iceberg.

   A saída do comando curl é semelhante a esta. O valor do prefixo do catálogo pode ser encontrado no campo overrides.prefix na resposta:

   {
     "overrides": {
       "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
       "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
     },
     "endpoints": [
       "GET /v1/{prefix}/namespaces",
       "POST /v1/{prefix}/namespaces",
       "GET /v1/{prefix}/namespaces/{namespace}",
       "HEAD /v1/{prefix}/namespaces/{namespace}",
       "DELETE /v1/{prefix}/namespaces/{namespace}",
       "POST /v1/{prefix}/namespaces/{namespace}/properties",
       "GET /v1/{prefix}/namespaces/{namespace}/tables",
       "POST /v1/{prefix}/namespaces/{namespace}/tables",
       "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
     ]
   }
   

2. Ative o modo de venda de credenciais e extraia a conta de serviço para conceder permissões com o seguinte comando:

   curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

   Substitua PREFIX pelo campo prefix da saída do comando anterior.

   A resposta ao comando curl contém a conta de serviço, semelhante a esta:

   {
     "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
     "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
     "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
   }
   

3. Para garantir que a conta de serviço do BigLake extraída na etapa anterior tenha as permissões necessárias para usar o modo de venda de credenciais, peça ao administrador para conceder a ela o papel de Usuário do objeto do Storage (roles/storage.objectUser) no bucket de armazenamento.

   Importante: conceda esse papel à conta de serviço do BigLake que você extraiu na etapa anterior, não à sua conta de usuário. Se a função não for concedida ao principal correto, poderão ocorrer erros de permissão.

Limitações

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

• Buckets multirregionais, birregionais e com posicionamento de região personalizado não são compatíveis.
• 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.

Configurar o catálogo REST do Iceberg

Cluster

Para usar o Spark com o catálogo REST do Iceberg no Dataproc, primeiro crie um cluster com o componente Iceberg:

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

Substitua:

• CLUSTER_NAME: um nome para o cluster.
• PROJECT_ID: o ID do projeto Google Cloud .
• REGION: a região do cluster do Dataproc.
• DATAPROC_VERSION: a versão da imagem do Dataproc, por exemplo, 2.2.

Depois de criar o cluster, configure sua sessão do Spark para usar o catálogo REST do 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

• CATALOG_NAME: um nome para seu catálogo REST do Iceberg.
• APP_NAME: um nome para a sessão do Spark.
• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena as tabelas Iceberg do BigLake.
• PROJECT_ID: o projeto que recebe a cobrança pelo uso do catálogo REST do 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.

Este exemplo não usa a venda de credenciais. Para usar a venda de credenciais, adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações do 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Os clusters do Dataproc são compatíveis com os fluxos de autorização do Google para o Iceberg nas seguintes versões:

• Versões de imagem 2.2 do Dataproc no Compute Engine 2.2.65 e mais recentes.
• Versões de imagem 2.3 do Dataproc no Compute Engine 2.3.11 e mais recentes.

Sem servidor

Envie uma carga de trabalho em lote do PySpark para o Google Cloud Serverless para Apache Spark com 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/v1/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.rest-metrics-reporting-enabled=false"

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 Dataproc.
• RUNTIME_VERSION: a versão do ambiente de execução do Serverless para Apache Spark, por exemplo, 2.2.
• CATALOG_NAME: um nome para seu catálogo REST do Iceberg.
• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena as tabelas Iceberg do BigLake.

Para usar a venda de credenciais, adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações do catálogo REST do Iceberg com um valor de vended-credentials. Para isso, adicione a seguinte linha às configurações do Serverless 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/v1/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.rest-metrics-reporting-enabled=false,
    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 Iceberg.

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

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

Trino

Para usar o Trino com o catálogo REST do Iceberg, crie um cluster do Dataproc com o componente 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/v1/restcatalog,\
trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
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 Dataproc.
• DATAPROC_VERSION: versão da imagem do Dataproc, por exemplo, 2.2.
• NETWORK_ID: ID da rede do cluster. Para mais informações, consulte Configuração de rede de um cluster do Dataproc.
• CATALOG_NAME: um nome para seu catálogo do Trino usando o catálogo REST do Iceberg.
• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena as tabelas Iceberg do BigLake.
• PROJECT_ID: o ID do projeto Google Cloud a ser usado para o BigLake Metastore.

Depois da criação do cluster, use SSH para se conectar à instância de VM principal e use a CLI do Trino da seguinte maneira:

trino

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

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

Importante: a venda de credenciais não é compatível com o Dataproc Trino.

Iceberg 1.10 ou mais recente

O 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 um exemplo de como configurar o Apache Spark para usar o catálogo REST do Iceberg do BigLake metastore.

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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

• CATALOG_NAME: um nome para seu catálogo REST do Iceberg.
• APP_NAME: um nome para a sessão do Spark.
• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena as tabelas Iceberg do BigLake.
• PROJECT_ID: o projeto que é faturado pelo uso do catálogo REST do 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.

O exemplo anterior não usa a venda de credenciais. Para usar a venda de credenciais, adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações do 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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Versões anteriores do Iceberg

Para versões de código aberto do Iceberg anteriores à 1.10, é possível configurar a autenticação OAuth padrão ao configurar 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/v1/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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Substitua:

• CATALOG_NAME: um nome para seu catálogo REST do Iceberg.
• APP_NAME: um nome para a sessão do Spark.
• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage que armazena as tabelas Iceberg do BigLake.
• PROJECT_ID: o projeto que é faturado pelo uso do catálogo REST do 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.

O exemplo anterior não usa a venda de credenciais. Para usar a venda de credenciais, adicione o cabeçalho X-Iceberg-Access-Delegation às solicitações do 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('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/v1/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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .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 Iceberg.

Criar um namespace

Spark

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

spark.sql("USE NAMESPACE_NAME;")

Substitua NAMESPACE_NAME por um nome para o namespace.

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Substitua:

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

Criar uma tabela

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Substitua:

• NAMESPACE_NAME: o nome do namespace.
• TABLE_NAME: um nome para a tabela

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

Substitua TABLE_NAME por um nome para a tabela.

Listar tabelas

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

Inserir dados na tabela

O exemplo a seguir insere dados de amostra na tabela:

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

Consultar uma tabela

O exemplo a seguir seleciona todos os dados da tabela:

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

O exemplo a seguir consulta a mesma tabela do BigQuery:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Substitua:

• CLOUD_STORAGE_BUCKET_NAME: o nome do bucket do Cloud Storage para seu catálogo REST do Iceberg. Por exemplo, se o URI for gs://iceberg_bucket, use iceberg_bucket.

• NAMESPACE_OR_SCHEMA_NAME: o namespace da tabela se você estiver usando o Spark ou o nome do esquema da tabela se estiver usando o Trino.

• TABLE_NAME: o nome da tabela.

Alterar um esquema de tabela

O exemplo a seguir adiciona uma coluna à tabela:

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Substitua:

• NAMESPACE_NAME: o nome do namespace.
• TABLE_NAME: um nome para a tabela

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

Substitua:

• SCHEMA_NAME: o nome do seu esquema
• TABLE_NAME: um nome para a tabela

Excluir uma tabela

O exemplo a seguir exclui a tabela do namespace especificado:

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Preços

Para detalhes dos preços, consulte Preços do BigLake.

A seguir

• Saiba mais sobre como gerenciar recursos do Iceberg com o metastore do BigLake.
• Saiba mais sobre outros recursos do metastore do BigLake.