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

O catálogo REST do Apache Iceberg no metastore do BigLake é a maneira recomendada de usar o metastore do BigLake para novos fluxos de trabalho. Ele cria interoperabilidade entre 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.

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.

Já o catálogo personalizado do Iceberg para o 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

Conheça o BigLake Metastore antes de continuar.

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

  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

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 venda de credenciais do catálogo:
  • 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:
  • Gerenciar recursos do catálogo e gravar dados de tabelas no modo sem venda de credenciais:

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 catálogo REST do Iceberg está sujeito às seguintes limitações:

  • 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.
  • O Trino só é compatível com a federação de catálogos do BigQuery ao usar o Dataproc em versões de imagem do Compute Engine 2.3.16 e mais recentes.

Recursos do catálogo

O catálogo REST do Apache Iceberg no metastore do BigLake usa uma hierarquia de recursos para organizar seus dados.

Recursos do catálogo REST do Apache Iceberg

A tabela a seguir mostra uma visão geral dos recursos usados pelo catálogo REST do Apache Iceberg no metastore do BigLake.

Recurso Descrição
Catálogo O contêiner de nível superior, um catálogo, permite organizar namespaces e tabelas em grupos lógicos dividindo-os em diferentes catálogos.
Namespace Um agrupamento lógico usado para organizar tabelas em um catálogo. Ele funciona como bancos de dados, esquemas ou diretórios.
Tabela As tabelas contêm definições de linhas e colunas que podem ser consultadas.

Catálogos compatíveis

Ao configurar o cliente, você especifica um local do depósito. Essa escolha determina como seu catálogo opera e se integra a outros serviços do Google Cloud.

Tipo de catálogo Descrição
Bucket do Cloud Storage Todos os dados de um catálogo são armazenados em um único bucket do Cloud Storage. Para dados compartilhados em vários buckets, são necessários vários catálogos.
Federação do BigQuery Permite usar o catálogo REST do Iceberg para gerenciar e consultar tabelas visíveis para o BigQuery. Para mais informações, consulte Usar a federação de catálogos com o BigQuery.

Detalhes do warehouse do catálogo

Recomendado

  • Data warehouse de bucket do Cloud Storage (gs://): essa é a abordagem padrão em que o catálogo gerencia diretamente os metadados e arquivos de dados do Iceberg em um bucket do Cloud Storage especificado por você. Essa opção oferece controle direto sobre o layout dos dados e é compatível com a venda de credenciais para controle de acesso detalhado. Isso permite criar e gerenciar tabelas do BigLake para Apache Iceberg.

    Por exemplo, se você criou um bucket para armazenar seu catálogo e o nomeou como iceberg-bucket, tanto o nome do catálogo quanto o do bucket serão iceberg-bucket. Isso será usado mais tarde ao consultar seu catálogo no BigQuery usando a sintaxe P.C.N.T. Por exemplo: my-project.biglake-catalog-id.quickstart_namespace.quickstart_table

Legado

  • Federação do BigQuery (bq://): essa abordagem permite usar o catálogo REST do Iceberg para gerenciar e consultar tabelas visíveis para o BigQuery sem precisar criar um recurso de catálogo. Para mais informações, consulte Usar a federação de catálogos com o BigQuery.

Estrutura de nomenclatura P.C.N.T.

Ao consultar tabelas do metastore do BigLake no BigQuery, você usa uma estrutura de nomenclatura de quatro partes, geralmente chamada de P.C.N.T:

  • Projeto: o ID do projeto Google Cloud que é proprietário do catálogo.
  • Catálogo: o nome do catálogo do BigLake Metastore.
  • Namespace: o namespace do Iceberg (equivalente a um conjunto de dados do BigQuery).
  • Tabela: o nome da tabela.

Por exemplo, my-project.biglake-catalog-id.my-namespace.my-table

Configurar o catálogo REST do Iceberg

Estas são as etapas gerais a seguir ao usar o catálogo REST do Apache Iceberg no BigLake Metastore:

  1. Entenda e escolha o local do data warehouse do catálogo, seja no Cloud Storage ou no BigQuery.
  2. Se você estiver usando um data warehouse do Cloud Storage gs://, crie um catálogo que aponte para o local do seu data warehouse.
  3. Configure seu aplicativo cliente para usar o catálogo REST do Iceberg.
  4. Crie um namespace ou esquema para organizar suas 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 de 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 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.

Credenciais do usuário final

Console

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

    Acessar o BigLake

  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 beta biglake iceberg catalogs create.

gcloud beta biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

Substitua:

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 catálogo REST do Iceberg a retornar credenciais de armazenamento com escopo reduzido especificando a delegação de acesso ao configurar o catálogo REST do Iceberg.

Console

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

    Acessar o BigLake

  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 de usuário do objeto de armazenamento no bucket de armazenamento.

Configurar aplicativo cliente

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

Cluster

Para usar o Spark com o catálogo REST do Iceberg no Dataproc, primeiro crie um cluster que inclua 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', '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(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: o nome do seu catálogo REST do Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • 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 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.

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/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 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=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,\
    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: o nome do seu catálogo REST do Iceberg.
  • 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 do catálogo REST do Iceberg com um valor de vended-credentials ao adicionar 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
  • Ambientes 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=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 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: o nome do seu catálogo do Trino usando o catálogo REST do Iceberg.
  • 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 metastore do BigLake.

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

trino --catalog=CATALOG_NAME

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.

Configurar com o modo de venda de credenciais

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 abaixo 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', '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(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: o nome do seu catálogo REST do Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • 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 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.

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 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 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', '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(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: o nome do seu catálogo REST do Iceberg.
  • APP_NAME: um nome para a sessão do Spark.
  • 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 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.

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 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}.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 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 catálogo REST do Iceberg.
  • SCHEMA_NAME: um nome para o esquema.

Consultar tabelas no BigQuery

A maneira de consultar tabelas criadas pelo catálogo REST do Iceberg no BigQuery depende de você estar usando um data warehouse de bucket do Cloud Storage ou federação do BigQuery.

  • Data warehouse de buckets do Cloud Storage: se você configurou o cliente com um caminho de data warehouse gs://, consulte tabelas do BigQuery usando o nome de quatro partes (P.C.N.T) project.catalog.namespace.table. O componente catalog é o nome do recurso do catálogo da metastore do BigLake. Para mais informações, consulte Consultar uma tabela.

  • Federação do BigQuery: se você configurou seu cliente com um caminho do data warehouse bq://, as tabelas criadas vão ficar visíveis no BigQuery e poderão ser consultadas diretamente usando o SQL padrão do BigQuery:

    SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

    Substitua:

    • NAMESPACE_NAME: o nome do namespace.
    • TABLE_NAME: o nome da tabela.

Usar a federação de catálogos com o BigQuery

É possível usar a interface do catálogo REST do Iceberg para gerenciar e consultar tabelas visíveis para o BigQuery. Os catálogos de federação do BigQuery não exigem a criação de um recurso de catálogo. Eles podem ser usados em qualquer projeto que tenha a API BigQuery ativada. Isso permite que você:

Como esses recursos são gerenciados pelo BigQuery, você precisa ter as permissões necessárias aplicáveis. A venda de credenciais não é compatível com catálogos federados.

Para ativar a federação, configure seu cliente com o formato de data warehouse bq://projects/PROJECT_ID no campo WAREHOUSE_PATH nos exemplos de configuração do cliente em Usar o catálogo REST do Iceberg. Também é possível incluir um local do BigQuery para restringir solicitações futuras a um único local usando o formato bq://projects/PROJECT_ID/locations/LOCATION.

Depois de configurar o cliente para federação, crie um namespace para suas tabelas federadas.

Spark

Para usar a federação de catálogos do BigQuery, inclua as cláusulas LOCATION e DBPROPERTIES:

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Substitua:

  • NAMESPACE_NAME: um nome para o namespace.
  • BUCKET_NAME: o bucket do Cloud Storage que você está usando com seu catálogo.
  • LOCATION: um local do BigQuery. O valor padrão é a multirregião US.

Trino

Para usar a federação de catálogos do BigQuery, inclua as propriedades LOCATION e gcp-region:

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
USE CATALOG_NAME.SCHEMA_NAME;

Substitua:

  • CATALOG_NAME: o nome do seu catálogo do Trino usando o catálogo REST do Iceberg.
  • SCHEMA_NAME: um nome para o esquema.
  • BUCKET_NAME: o bucket do Cloud Storage que você está usando com seu catálogo.
  • LOCATION: um local do BigQuery. O valor padrão é a multirregião US.

Preços

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

A seguir