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 Google Cloud Lakehouse.

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. Os fluxos de trabalho atuais podem continuar usando o catálogo REST, mas ele oferece uma experiência mais padronizada e rica em recursos.

Antes de começar

Familiarize-se com o catálogo de tempo 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 as versões de imagem 2.3.16 e mais recentes do Serviço gerenciado para Apache Spark no Compute Engine 2.3.
  • 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 gerenciadas do catálogo REST do Lakehouse para Apache Iceberg, 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 nas regiões 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 do Lakehouse Iceberg. 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, primeiro crie um cluster que inclua o componente do Apache 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 Serviço Gerenciado para Apache Spark.
  • DATAPROC_VERSION: a versão da imagem do Serviço Gerenciado para Apache Spark, por exemplo, 2.2.

Depois de criar o cluster, configure sua sessão do Spark para usar 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

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 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/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 no 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 não é compatível com o Serviço Gerenciado para Apache Spark 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.

Consultar tabelas no BigQuery

A forma de consultar as tabelas criadas pelo endpoint do catálogo REST do Apache 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 as tabelas do BigQuery usando o nome de quatro partes (P.C.N.T) project.catalog.namespace.table. Para mais informações sobre a estrutura P.C.N.T, consulte Conceitos do catálogo REST do Iceberg. O componente catalog é o nome do recurso do catálogo do ambiente de execução do Lakehouse. Para mais informações sobre como consultar tabelas, 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

Para saber mais sobre a federação de catálogos, consulte Conceitos do catálogo REST do Iceberg. Para ativar a federação, configure o cliente com o formato de data warehouse bq://projects/PROJECT_ID no campo WAREHOUSE_PATH nos exemplos de configuração do cliente em Configurar o aplicativo cliente. 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.

Como esses recursos são gerenciados pelo BigQuery, você precisa ter as permissões necessárias aplicáveis.

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 endpoint do catálogo REST do Apache 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.

A seguir