Esta página foi traduzida pela API Cloud Translation.

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

O catálogo REST do Apache Iceberg gerido no metastore do BigLake cria interoperabilidade entre todos os seus motores de consulta, oferecendo uma única origem de verdade para todos os seus dados do Iceberg. Permite que os motores de consulta, como o Apache Spark, descubram, leiam metadados e façam a gestão de tabelas Iceberg de forma consistente.

As tabelas Iceberg que usa com o catálogo REST do Iceberg são denominadas tabelas BigLake para o Apache Iceberg (pré-visualização). Estas são tabelas Iceberg que cria a partir de motores de código aberto e armazena no Cloud Storage. Podem ser lidos por motores de código aberto ou pelo BigQuery. As gravações só são suportadas a partir de motores de código aberto. Neste documento, referimo-nos a estas tabelas como tabelas Iceberg do BigLake.

Antes de começar

Verify that billing is enabled for your Google Cloud project.
Saiba como verificar se a faturação está ativada num projeto.
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
Opcional: peça a um administrador para configurar a emissão de credenciais pela primeira vez.
Opcional: compreenda como funciona o metastore do BigLake e por que motivo o deve usar.

Funções necessárias

Para receber as autorizações de que precisa para usar o catálogo REST do Iceberg no metastore do BigLake, peça ao seu administrador que lhe conceda as seguintes funções de IAM:

Executar tarefas administrativas, como gerir o acesso de utilizadores ao catálogo, o acesso ao armazenamento e o modo de credenciais do catálogo:
- Administrador do BigLake (roles/biglake.admin) no projeto
- Administrador de armazenamento (roles/storage.admin) no contentor do Cloud Storage
Ler dados de tabelas no modo de fornecimento de credenciais: Visualizador do BigLake (roles/biglake.viewer) no projeto
Escrever dados de tabelas no modo de emissão de credenciais: Editor do BigLake (roles/biglake.editor) no projeto
Ler recursos do catálogo e dados de tabelas no modo de vendas sem credenciais:
- Visualizador do BigLake (roles/biglake.viewer) no projeto
- Storage Object Viewer (roles/storage.objectViewer) no contentor do Cloud Storage
Faça a gestão dos recursos do catálogo e escreva dados de tabelas no modo de vendas sem credenciais:
- Editor do BigLake (roles/biglake.editor) no projeto
- Utilizador de objetos de armazenamento (roles/storage.objectUser) no contentor do Cloud Storage

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Configure o modo de emissão de credenciais

O modo de fornecimento de credenciais é um mecanismo de delegação de acesso ao armazenamento que permite aos administradores do metastore do BigLake controlar as autorizações diretamente nos recursos do metastore do BigLake, eliminando a necessidade de os utilizadores do catálogo terem acesso direto aos contentores do Cloud Storage. Permite que os administradores do BigLake concedam autorizações aos utilizadores em ficheiros de dados específicos.

Um administrador do catálogo ativa a emissão de credenciais no cliente do catálogo REST do Iceberg.

Enquanto utilizador do catálogo, pode instruir o catálogo REST do Iceberg a devolver credenciais de armazenamento com âmbito 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 o artigo Configure um motor de consultas com o catálogo REST do Iceberg.

Para inicializar o catálogo e ativar o modo de emissão de credenciais, siga estes passos.

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 o seguinte:

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

O resultado do comando curl é semelhante ao seguinte. 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}"
  ]
}

Ative o modo de emissão de credenciais e extraia a conta de serviço à qual conceder autorizaçõ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 do resultado do comando anterior.

O resultado do comando curl contém a conta de serviço, semelhante ao seguinte:

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

Para garantir que a conta de serviço do BigLake que extraiu no passo anterior tem as autorizações necessárias para usar o modo de venda de credenciais, peça ao seu administrador para lhe conceder a função de utilizador de objetos de armazenamento (roles/storage.objectUser) no contentor de armazenamento.

Importante: tem de conceder esta função à conta de serviço do BigLake que extraiu no passo anterior e não à sua conta de utilizador. Se não conceder a função ao principal correto, podem ocorrer erros de autorização.

Limitações

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

Os contentores multirregionais, os contentores de duas regiões e os contentores com posicionamento de regiões personalizado não são suportados.
Quando usar o modo de fornecimento de credenciais, tem de definir a propriedade io-impl como org.apache.iceberg.gcp.gcs.GCSFileIO. A predefinição, org.apache.iceberg.hadoop.HadoopFileIO, não é suportada.

Configure 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 o seguinte:

CLUSTER_NAME: um nome para o cluster.
PROJECT_ID: o ID do seu Google Cloud projeto.
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 a 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 o seguinte:

CATALOG_NAME: um nome para o seu catálogo REST do Iceberg.
APP_NAME: um nome para a sua sessão do Spark.
CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage que armazena as tabelas Iceberg do BigLake.
PROJECT_ID: o projeto que é faturado pela utilização do catálogo REST do Iceberg, que pode ser diferente do projeto proprietário do contentor do Cloud Storage. Para ver detalhes sobre a configuração do projeto quando usa uma API REST, consulte os Parâmetros do sistema.

Este exemplo não usa a venda de credenciais. Para usar a emissão de credenciais, tem de adicionar o cabeçalho X-Iceberg-Access-Delegation aos pedidos de catálogo REST do Iceberg com um valor de vended-credentials, adicionando a seguinte linha ao criador SparkSession:

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

Exemplo com a venda de credenciais

O exemplo seguinte configura o motor de consulta com a emissão 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 secção Cabeçalhos na RESTCatalog da documentação do Iceberg.

Os clusters do Dataproc suportam fluxos de autorização da Google para o Iceberg nas seguintes versões:

Versões de imagens do Dataproc no Compute Engine 2.2 2.2.65 e posteriores.
Versões de imagens do Dataproc no Compute Engine 2.3 2.3.11 e posteriores.

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 o seguinte:

PYSPARK_FILE: o caminho do gs:// Cloud Storage para o ficheiro da aplicação PySpark.
PROJECT_ID: o ID do seu Google Cloud projeto.
REGION: a região da carga de trabalho em lote do Dataproc.
RUNTIME_VERSION: a versão de tempo de execução do Serverless para Apache Spark, por exemplo, 2.2.
CATALOG_NAME: um nome para o seu catálogo REST do Iceberg.
CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage que armazena as tabelas Iceberg do BigLake.

Para usar a emissão de credenciais, tem de adicionar o cabeçalho X-Iceberg-Access-Delegation aos pedidos do catálogo REST do Iceberg com um valor de vended-credentials, adicionando 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 a venda de credenciais

O exemplo seguinte configura o motor de consulta com a emissão 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 secção Cabeçalhos na RESTCatalog da documentação do Iceberg.

O Serverless para Apache Spark suporta fluxos de autorização da Google para o Iceberg nas seguintes versões de tempo de execução:

Serverless para Apache Spark 2.2 tempos de execução 2.2.60 e posteriores
Tempos de execução 2.3.10 e posteriores do Serverless para Apache Spark 2.3

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 seguinte cria um catálogo do Trino com o nome 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 o seguinte:

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 o artigo Configuração de rede do cluster do Dataproc.
CATALOG_NAME: um nome para o seu catálogo do Trino que usa o catálogo REST do Iceberg.
CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage que armazena as tabelas Iceberg do BigLake.
PROJECT_ID: o ID do seu projeto Google Cloud para usar no metastore do BigLake.

Após a criação do cluster, use o SSH para estabelecer ligação à instância da VM principal e, em seguida, use a CLI do Trino da seguinte forma:

trino

O Dataproc Trino suporta fluxos de autorização da Google para o Iceberg nas seguintes versões:

Versões de tempo de execução 2.2 do Dataproc no Compute Engine 2.2.65 e posteriores
Versões de tempo de execução 2.3 do Dataproc no Compute Engine 2.3.11 e posteriores
O Dataproc no Compute Engine 3.0 não é suportado.

Iceberg 1.10 ou posterior

As versões de código aberto do Iceberg 1.10 e posteriores têm suporte incorporado para fluxos de autorização da Google em GoogleAuthManager. Segue-se um exemplo de como configurar o Apache Spark para usar o catálogo REST do Iceberg do metastore do BigLake.

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 o seguinte:

CATALOG_NAME: um nome para o seu catálogo REST do Iceberg.
APP_NAME: um nome para a sua sessão do Spark.
CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage que armazena as tabelas Iceberg do BigLake.
PROJECT_ID: o projeto que é faturado pela utilização do catálogo REST do Iceberg, que pode ser diferente do projeto proprietário do contentor do Cloud Storage. Para ver detalhes sobre a configuração do projeto quando usa uma API REST, consulte os Parâmetros do sistema.

O exemplo anterior não usa a venda de credenciais. Para usar a emissão de credenciais, tem de adicionar o cabeçalho X-Iceberg-Access-Delegation aos pedidos de catálogo REST do Iceberg com um valor de vended-credentials, adicionando a seguinte linha ao criador SparkSession:

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

Exemplo com a venda de credenciais

O exemplo seguinte configura o motor de consulta com a emissão 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 secção Cabeçalhos na RESTCatalog da documentação do Iceberg.

Lançamentos anteriores do Iceberg

Para versões open source do Iceberg anteriores à 1.10, pode 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/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 o seguinte:

CATALOG_NAME: um nome para o seu catálogo REST do Iceberg.
APP_NAME: um nome para a sua sessão do Spark.
CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage que armazena as tabelas Iceberg do BigLake.
PROJECT_ID: o projeto que é faturado pela utilização do catálogo REST do Iceberg, que pode ser diferente do projeto proprietário do contentor do Cloud Storage. Para ver detalhes sobre a configuração do projeto quando usa uma API REST, consulte os Parâmetros do sistema.
TOKEN: o seu token de autenticação, que é válido durante uma hora. Por exemplo, um token gerado através de gcloud auth application-default print-access-token.

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

Exemplo com a venda de credenciais

O exemplo seguinte configura o motor de consulta com a emissão 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 secção Cabeçalhos na RESTCatalog da documentação do Iceberg.

Crie um espaço de nomes

Spark

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

spark.sql("USE NAMESPACE_NAME;")

Substitua NAMESPACE_NAME por um nome para o seu espaço de nomes.

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Substitua o seguinte:

CATALOG_NAME: um nome para o seu catálogo do Trino que usa o catálogo REST do Iceberg.
SCHEMA_NAME: um nome para o seu 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 o seguinte:

NAMESPACE_NAME: o nome do seu espaço de nomes
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 sua tabela.

Listar tabelas

Spark

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

Trino

SHOW TABLES;

Insira dados na tabela

O exemplo seguinte insere dados de exemplo 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 seguinte seleciona todos os dados da tabela:

Spark

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

Trino

SELECT * FROM TABLE_NAME;

O exemplo seguinte consulta a mesma tabela do BigQuery:

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Substitua o seguinte:

CLOUD_STORAGE_BUCKET_NAME: o nome do contentor do Cloud Storage para o seu catálogo REST do Iceberg. Por exemplo, se o URI for gs://iceberg_bucket, use iceberg_bucket.
NAMESPACE_OR_SCHEMA_NAME: o espaço de nomes da tabela se usar o Spark ou o nome do esquema da tabela se usar o Trino.
TABLE_NAME: o nome da sua mesa.

Altere um esquema de tabela

O exemplo seguinte adiciona uma coluna à tabela:

Spark

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

Substitua o seguinte:

NAMESPACE_NAME: o nome do seu espaço de nomes
TABLE_NAME: um nome para a tabela

Trino

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

Substitua o seguinte:

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

Elimine uma tabela

O exemplo seguinte elimina a tabela do espaço de nomes indicado:

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Preços

Para ver detalhes de preços, consulte os preços do BigLake.

O que se segue?

Saiba mais sobre a gestão de recursos do Iceberg com o metastore do BigLake.
Saiba mais sobre as funcionalidades adicionais do metastore do BigLake.