Configurar o catálogo REST do Lakehouse Iceberg

Para novos catálogos, recomendamos instâncias do catálogo do Iceberg criadas no catálogo de ambientes 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 suas tabelas do Lakehouse do Google Cloud.

Essa abordagem é uma boa opção se você usa mecanismos de OSS ou de terceiros compatíveis 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.

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

Antes de começar

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

Se você tiver tabelas do Apache Iceberg da versão 1 (V1), faça upgrade delas antes de usá-las com o endpoint do catálogo REST do Apache Iceberg. Para mais informações, consulte Fazer upgrade de tabelas do Iceberg V1 para V2.

  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 a fim de 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:
  • Registrar tabelas em um catálogo do BigLake: Administrador do BigLake (roles/biglake.admin) no projeto.
  • 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 de tabelas, 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 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) em todos os buckets associados do Cloud Storage. Depois de criar o catálogo, conceda explicitamente o papel de usuário de objetos do Storage (roles/storage.objectUser) em todos os buckets de armazenamento associados à conta de serviço do catálogo de tempo de execução do Lakehouse provisionada automaticamente.
  • Ler recursos do catálogo e dados da tabela no modo sem venda de credenciais:
  • Gerencie recursos de catálogo e grave dados de tabela no modo sem venda de credenciais:
  • Realize operações de linguagem de manipulação de dados (DML) com a federação de catálogo do BigQuery. Nem todas as tabelas federadas do BigQuery são mutáveis. A DML não é permitida em tabelas gerenciadas do Iceberg:
    • Editor de dados do BigQuery (roles/bigquery.dataEditor) no projeto
    • Administrador do Storage (roles/storage.admin) em todos os buckets associados 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

  • As tabelas do Apache Iceberg V2 (GA) e V3 (prévia) são compatíveis. Não há suporte para tabelas do Iceberg V1. Antes de usar tabelas V1 com o endpoint do catálogo REST do Apache Iceberg, é necessário fazer upgrade para uma versão compatível.
  • O Trino só é compatível com a federação de catálogos do BigQuery ao usar o Serviço Gerenciado para Apache Spark no Compute Engine 2.3 versões 2.3.16 e mais recentes.
  • Ao usar o modo de venda de credenciais, defina a propriedade io-impl como org.apache.iceberg.gcp.gcs.GCSFileIO. O padrão, org.apache.iceberg.hadoop.HadoopFileIO, não é compatível.
  • No momento, não há suporte para buckets de namespaces hierárquicos no modo de venda de credenciais.

Limitações da tabela

  • Não é possível criar ou modificar tabelas no endpoint do catálogo REST do Apache Iceberg usando instruções da linguagem de definição de dados (DDL) ou da linguagem de manipulação de dados (DML) do BigQuery. É possível modificar essas tabelas usando a API BigQuery (com a ferramenta de linha de comando bq ou bibliotecas de cliente), mas isso pode causar mudanças incompatíveis com o mecanismo externo.
  • 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 no nível de linha e coluna.
  • Não é permitido definir as propriedades da tabela do Iceberg write.data.path ou write.metadata.path com valores diferentes dos padrões.
  • Os caminhos de tabela precisam estar aninhados no caminho do namespace principal (por exemplo, gs://{namespace_path}/.../{table_name}). Para evitar conflitos e melhorar a segurança, um sufixo de string aleatório é anexado automaticamente ao local resultante (por exemplo, gs://{namespace_path}/{table_name}/{random_suffix}).

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 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 tipo de catálogo. Isso pode configurar um catálogo de vários buckets (bl://) (recomendado) ou um catálogo de um único bucket (gs://).
  2. Crie um catálogo que aponte para o local do seu depósito.
  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 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 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. Em Tipo de catálogo, selecione Bucket do Cloud Storage.

  4. Insira ou procure o bucket do Cloud Storage a ser usado com seu catálogo. Para um catálogo de bucket único (gs://), só é possível ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.

  5. Em Método de autenticação, selecione Credenciais do usuário final.

  6. Clique em Criar.

gcloud

Use o comando gcloud biglake iceberg catalogs create.

Criar um catálogo de vários buckets (bl://) (recomendado)

Para criar um catálogo de vários buckets (bl://), que é o recomendado, execute o seguinte comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

Criar um catálogo de bucket único (gs://)

Para criar um catálogo de bucket único (gs://), execute o seguinte comando:

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

Substitua:

  • CATALOG_NAME: um nome para o catálogo. Para catálogos de vários buckets (bl://), que são recomendados, esse é o nome personalizado do catálogo. Para catálogos de bucket único (gs://), isso corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST. Esse nome também é usado como o identificador do catálogo ao consultar essas tabelas no BigQuery.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • DEFAULT_LOCATION: especifique o local de armazenamento padrão do catálogo. É possível especificar um bucket (gs://my-bucket) ou um subcaminho (gs://my-bucket/path). Todos os namespaces e tabelas no catálogo precisam estar no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não poderá criar namespaces ou tabelas em gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS: (opcional) lista separada por vírgulas de locais de armazenamento permitidos adicionais, no formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se você especificar um caminho (como gs://my-bucket/path), todos os namespaces ou tabelas nesse bucket precisarão estar nesse caminho. Todos os locais de armazenamento em nuvem configurados no local padrão e nos locais restritos precisam estar no mesmo grupo de região geográfica ou jurisdição (como Estados Unidos, Europa, Canadá ou Ásia). Por exemplo, não é possível misturar um bucket nos EUA com um na Europa. Para conferir uma lista de locais compatíveis, consulte Locais do Lakehouse. Aviso de segurança:evite configurar caminhos sobrepostos com outros catálogos para impedir a exposição não autorizada de credenciais. Para mais informações, consulte Armazenamento em vários buckets.
  • 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 na região 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) em todos os buckets associados do Cloud Storage. Por padrão, ele não tem acesso. 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 Tipo de catálogo, selecione Bucket do Cloud Storage.

  4. Insira ou procure o bucket do Cloud Storage a ser usado com seu catálogo. Para um catálogo de bucket único (gs://), só é possível ter um catálogo por bucket, e o nome do catálogo precisa corresponder ao nome do bucket.

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

  6. Clique em Criar.

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

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

  8. 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 de objetos do Storage em todos os buckets de armazenamento associados.

gcloud

Use o comando gcloud biglake iceberg catalogs create.

Criar um catálogo de vários buckets (bl://) (recomendado)

Para criar um catálogo de vários buckets (bl://), que é o recomendado, execute o seguinte comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Criar um catálogo de bucket único (gs://)

[!CAUTION] Tipo de catálogo legado. Não é recomendável usar a configuração legada de bucket único em novos projetos. Essa configuração restringe seu catálogo a um único bucket e bloqueia o nome do catálogo para o nome do bucket.

Para criar um catálogo de bucket único (gs://), execute o seguinte comando:

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials

Substitua:

  • CATALOG_NAME: um nome para o catálogo. Para catálogos de vários buckets (bl://), que é o recomendado, esse é o nome personalizado do catálogo. Para catálogos de bucket único (gs://), isso corresponde ao ID do bucket do Cloud Storage usado com o catálogo REST. Esse nome também é usado como o identificador do catálogo ao consultar essas tabelas no BigQuery.
  • PROJECT_ID: o ID do projeto Google Cloud .
  • DEFAULT_LOCATION: especifique o local de armazenamento padrão do catálogo. É possível especificar um bucket (gs://my-bucket) ou um subcaminho (gs://my-bucket/path). Todos os namespaces e tabelas no catálogo precisam estar no caminho especificado. Por exemplo, se você especificar gs://my-bucket/path, não poderá criar namespaces ou tabelas em gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS: (opcional) lista separada por vírgulas de locais de armazenamento permitidos adicionais, no formato gs://my-bucket-1/...,gs://my-bucket-2/.... Se você especificar um caminho (como gs://my-bucket/path), todos os namespaces ou tabelas nesse bucket precisarão estar nesse caminho. Todos os locais de armazenamento em nuvem configurados no local padrão e nos locais restritos precisam estar no mesmo grupo de região geográfica ou jurisdição (como Estados Unidos, Europa, Canadá ou Ásia). Por exemplo, não é possível misturar um bucket nos EUA com um na Europa. Para conferir uma lista de locais compatíveis, consulte Locais do Lakehouse. Aviso de segurança:evite configurar caminhos sobrepostos com outros catálogos para impedir a exposição não autorizada de credenciais. Para mais informações, consulte Armazenamento em vários buckets.

  • 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 na região 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) em todos os buckets do Storage associados à conta de serviço do catálogo de ambientes de execução do Lakehouse provisionada automaticamente.

Fazer upgrade de um catálogo

Se você tiver um catálogo de bucket único (gs://), faça upgrade para um catálogo de vários buckets (bl://), que é o recomendado. Com o upgrade, é possível associar vários buckets e configurar locais restritos, mantendo o nome original do catálogo.

Para fazer upgrade do catálogo, consulte Atualizar um catálogo.

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

Crie um cluster do Serviço Gerenciado para Apache Spark no Compute Engine usando propriedades de configuração simplificadas (recomendado) ou especificando propriedades manualmente.

Crie um cluster com a propriedade de catálogo:

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

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 de imagem do Serviço Gerenciado para Apache Spark, por exemplo, 2.3.
  • CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog). Ele pode ser o mesmo que CATALOG_ID.
  • CATALOG_ID: o ID do catálogo que você criou.

No arquivo do aplicativo PySpark, crie o SparkSession sem especificar as configurações de catálogo:

from pyspark.sql import SparkSession

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

Configuração manual

Se você não usar a propriedade de configuração simplificada, crie um cluster como descrito acima, mas sem a flag --properties. Em seguida, configure seu SparkSession manualmente:

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_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') \
  .getOrCreate()

Substitua:

  • CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog).
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Para catálogos do BigLake, use bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Para catálogos bucket do Cloud Storage, 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('spark.sql.defaultCatalog', 'CATALOG_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(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .getOrCreate()

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

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

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

Sem servidor

Envie uma carga de trabalho em lote do PySpark para o Serviço Gerenciado para Apache Spark usando propriedades de configuração simplificadas (recomendado) ou especificando propriedades manualmente.

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

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

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.3.
  • CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog). Ele pode ser o mesmo que CATALOG_ID.
  • CATALOG_ID: o ID do catálogo que você criou.

No arquivo do aplicativo PySpark, crie o SparkSession sem especificar as configurações de catálogo:

from pyspark.sql import SparkSession

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

Configuração manual

Se você não usar a propriedade de configuração simplificada, especifique manualmente as configurações do catálogo:

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.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Substitua:

  • PYSPARK_FILE: o caminho do Cloud Storage gs:// para o arquivo do aplicativo PySpark.
  • 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.3.
  • CATALOG_NAME: um nome para o catálogo local do Spark (por exemplo, my_catalog).
  • REST_API_VERSION: defina como v1 para a versão estável da API.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Para catálogos do BigLake, use bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Para catálogos bucket do Cloud Storage, 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, 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 adicionando 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=WAREHOUSE_PATH,\
    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.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

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.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Para catálogos do BigLake, use bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Para catálogos bucket do Cloud Storage, 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 é compatível apenas com a versão 481 e mais recentes do Trino.

Apache Iceberg 1.10 ou mais recente

O Apache Iceberg 1.10 de código aberto e versões mais recentes têm suporte integrado para fluxos de autorização do Google em GoogleAuthManager. Confira um exemplo de como configurar o 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: um nome para o catálogo local do Spark (por exemplo, my_catalog).
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Para catálogos do BigLake, use bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Para catálogos bucket do Cloud Storage, 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', '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}.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: um nome para o catálogo local do Spark (por exemplo, my_catalog).
  • APP_NAME: um nome para a sessão do Spark.
  • REST_API_VERSION: defina como v1 para a versão estável da API.
  • WAREHOUSE_PATH: o caminho para seu data warehouse. Para catálogos do BigLake, use bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Para catálogos bucket do Cloud Storage, 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', '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}.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.

Console

  1. No console Google Cloud , acesse Lakehouse.

    Acessar o lakehouse

  2. Selecione um catálogo ou crie um, caso ainda não tenha.

  3. Na barra de menus, clique em + Criar namespace.

  4. Em Nome do namespace, insira um nome exclusivo.

  5. Em Local, especifique o caminho a ser associado ao namespace:

    • Vários buckets (bl://) (recomendado): é possível definir qualquer local personalizado, desde que ele esteja em um local permitido pelo catálogo (default_location ou restricted_locations). Se você não especificar um local, o namespace será criado no local padrão do catálogo (por exemplo, gs://{path-to-default-location}/{namespace_name}). Os catálogos de vários buckets (bl://), que são recomendados, não podem ser gerenciados no console.
    • single-bucket (gs://): o local do namespace é herdado automaticamente do bucket único do catálogo.

  6. Clique em Criar.

Spark

Data warehouse do Cloud Storage

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

Substitua NAMESPACE_NAME por um nome para o namespace.

Trino

Data warehouse do Cloud Storage

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

Substitua:

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

A seguir