Esta página foi traduzida pela API Cloud Translation.

Criar uma tabela Apache Iceberg com metadados no Metastore do BigQuery

Neste documento, mostramos como criar uma tabela do Apache Iceberg com metadados no Metastore do BigQuery usando o serviço Dataproc Jobs, a CLI do Spark SQL ou a interface da Web Zeppelin executada em um cluster do Dataproc.

Antes de começar

Se ainda não tiver feito isso, crie um projeto do Google Cloud , um bucket do Cloud Storage e um cluster do Dataproc.

Configurar o projeto
Crie um bucket do Cloud Storage no seu projeto.
1. In the Google Cloud console, go to the Cloud Storage Buckets page.
  Go to Buckets page
2. Click Create bucket.
3. On the Create a bucket page, enter your bucket information. To go to the next step, click Continue.
  - For Name your bucket, enter a name that meets the bucket naming requirements.
  - For Choose where to store your data, do the following:
    - Select a Location type option.
    - Select a Location option.
  - For Choose a default storage class for your data, select a storage class.
  - For Choose how to control access to objects, select an Access control option.
  - For Advanced settings (optional), specify an encryption method, a retention policy, or bucket labels.
4. Click Create.
Crie um cluster do Dataproc Para economizar recursos e custos, é possível criar um cluster do Dataproc de nó único para executar os exemplos apresentados neste documento.
- A sub-rede na região em que o cluster é criado precisa ter o Acesso privado do Google (PGA, na sigla em inglês) ativado.
  Por padrão, as VMs do cluster do Dataproc, criadas com uma versão de imagem 2.2 (padrão) ou mais recente, têm apenas endereços IP internos. Para permitir que as VMs do cluster se comuniquem com as APIs do Google, ative o Acesso privado do Google na sub-rede de rede default (ou nome de rede especificado pelo usuário, se aplicável) na região em que o cluster é criado.
  .
- Se você quiser executar o exemplo de interface da Web do Zeppelin neste guia, use ou crie um cluster do Dataproc com o componente opcional do Zeppelin ativado.
Conceder papéis a uma conta de serviço personalizada (se necessário): por padrão, as VMs do cluster do Dataproc usam a conta de serviço padrão do Compute Engine para interagir com o Dataproc. Se você quiser especificar uma conta de serviço personalizada ao criar o cluster, ela precisará ter o papel Dataproc Worker (roles/dataproc.worker) ou um papel personalizado com as permissões necessárias.

Mapeamento do banco de dados do OSS para o conjunto de dados do BigQuery

Observe o seguinte mapeamento entre o banco de dados de código aberto e os termos do conjunto de dados do BigQuery:

Banco de dados de OSS	Conjunto de dados do BigQuery
Namespace, Database	Conjunto de dados
Tabela particionada ou não particionada	Tabela
Ver	Ver

Criar uma tabela Iceberg

Esta seção mostra como criar uma tabela Iceberg com metadados no Metastore do BigQuery enviando um código do Spark SQL para o serviço do Dataproc, a CLI do Spark SQL e a interface da Web do componente Zeppelin, que são executados em um cluster do Dataproc.

Job do Dataproc

É possível enviar um job para o serviço do Dataproc enviando-o para um cluster do Dataproc usando o Console do Google Cloud ou o Google Cloud CLI, ou por uma solicitação HTTP REST ou uma chamada programática gRPC do Dataproc Bibliotecas de cliente do Cloud para a API Dataproc Jobs.

Os exemplos desta seção mostram como enviar um job do Dataproc Spark SQL para o serviço do Dataproc para criar uma tabela Iceberg com metadados no BigQuery usando a CLI gcloud, o console do Google Cloud ou a API REST do Dataproc.

Preparar arquivos de job

Siga as etapas abaixo para criar um arquivo de job do Spark SQL. O arquivo contém comandos do Spark SQL para criar e atualizar uma tabela Iceberg.

Em uma janela de terminal local ou no Cloud Shell, use um editor de texto, como vi ou nano, para copiar os comandos abaixo em um arquivo iceberg-table.sql e salve o arquivo no diretório atual.

USE CATALOG_NAME;
CREATE NAMESPACE IF NOT EXISTS example_namespace;
USE example_namespace;
DROP TABLE IF EXISTS example_table;
CREATE TABLE example_table (id int, data string) USING ICEBERG LOCATION 'gs://BUCKET/WAREHOUSE_FOLDER';
INSERT INTO example_table VALUES (1, 'first row');
ALTER TABLE example_table ADD COLUMNS (newDoubleCol double);
DESCRIBE TABLE example_table;

Substitua:

CATALOG_NAME: nome do catálogo do Iceberg.
BUCKET e WAREHOUSE_FOLDER: bucket e pasta do Cloud Storage usados para o repositório Iceberg.

Use a ferramenta gsutil para copiar o iceberg-table.sql local para seu bucket no Cloud Storage.
```
gsutil cp iceberg-table.sql gs://BUCKET/
```

Em seguida, faça o download e copie o arquivo JAR iceberg-spark-runtime-3.5_2.12-1.5.2 para o Cloud Storage.

Em uma janela de terminal local ou no Cloud Shell, execute o comando curl abaixo para fazer o download do arquivo JAR iceberg-spark-runtime-3.5_2.12-1.5.2 para o diretório atual.

curl -o iceberg-spark-runtime-3.5_2.12-1.5.2.jar https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.5.2/iceberg-spark-runtime-3.5_2.12-1.5.2.jar

Use a ferramenta gsutil para copiar o arquivo JAR iceberg-spark-runtime-3.5_2.12-1.5.2 local do diretório atual para o bucket no Cloud Storage.
```
gsutil cp iceberg-spark-runtime-3.5_2.12-1.5.2.jar gs://BUCKET/
```

Enviar o job do Spark SQL

Selecione uma guia para seguir as instruções e enviar o job do Spark SQL para o serviço do Dataproc usando a CLI gcloud, o console do Google Cloud ou a API REST do Dataproc.

gcloud

Execute o comando gcloud dataproc jobs submit spark-sql localmente em uma janela de terminal local ou no Cloud Shell para enviar o job do Spark SQL e criar a tabela Iceberg.
```
gcloud dataproc jobs submit spark-sql \
    --project=PROJECT_ID \
    --cluster=CLUSTER_NAME \
    --region=REGION \
    --jars="gs://BUCKET/1.5.2/iceberg-spark-runtime-3.5_2.12-1.5.2.jar,gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar" \
    --properties="spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog,spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID,spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION,spark.sql.catalog.CATALOG_NAME.warehouse=gs://BUCKET/WAREHOUSE_FOLDER" \
    -f="gs://BUCKETiceberg-table.sql"
```
Observações:
- PROJECT_ID: o ID do projeto do Google Cloud . Os IDs dos projetos estão listados na seção Informações do projeto no Painel do console do Google Cloud.
- CLUSTER_NAME: o nome do cluster do Dataproc.
- REGION: a região do Compute Engine em que o cluster está localizado.
- CATALOG_NAME: nome do catálogo do Iceberg.
- BUCKET e WAREHOUSE_FOLDER: bucket e pasta do Cloud Storage usados para o repositório Iceberg.
- LOCATION: um local do BigQuery compatível. O local padrão é "EUA".
- --jars: os jars listados são necessários para criar metadados de tabela no Metastore do BigQuery.
- --properties: Propriedades do catálogo.
- -f: o arquivo de job iceberg-table.sql que você copiou para seu bucket no Cloud Storage.

Confira a descrição da tabela na saída do terminal quando o job for concluído.

Time taken: 2.194 seconds
id                      int
data                    string
newDoubleCol            double
Time taken: 1.479 seconds, Fetched 3 row(s)
Job JOB_ID finished successfully.

Para conferir os metadados da tabela no BigQuery
1. No Console do Google Cloud, acesse a página BigQuery.
  
  Acessar o BigQuery Studio
2. Acessar metadados da tabela Iceberg.

Console

Siga as etapas abaixo para usar o console do Google Cloud e enviar o job do Spark SQL para o serviço do Dataproc e criar uma tabela Iceberg com metadados no Metastore do BigQuery.

No console do Google Cloud, acesse o Dataproc e Enviar um job.

Acesse a página "Enviar um job" e preencha os seguintes campos:

ID do job: aceite o ID sugerido ou insira o seu.
Região: selecione a região em que o cluster está localizado.
Cluster: selecione o cluster.
Tipo de job: selecione SparkSql.
Tipo de origem da consulta: selecione Query file.
Arquivo de consulta: insira gs://BUCKET/iceberg-table.sql

Arquivos JAR: insira o seguinte:

gs://BUCKET/iceberg-spark-runtime-3.5_2.12-1.5.2.jar,gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar

Propriedades: clique em Adicionar propriedade cinco vezes para criar uma lista de cinco campos de entrada key value e, em seguida, copie os pares de Chave e Valor abaixo para definir cinco propriedades.

#	Chave	Valor
1.	`spark.sql.catalog.CATALOG_NAME`	`org.apache.iceberg.spark.SparkCatalog`
2.	`spark.sql.catalog.CATALOG_NAME.catalog-impl`	`org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog`
3.	`spark.sql.catalog.CATALOG_NAME.gcp_project`	`PROJECT_ID`
4.	`spark.sql.catalog.CATALOG_NAME.gcp_location`	`LOCATION`
5.	`spark.sql.catalog.CATALOG_NAME.warehouse`	`gs://BUCKET/WAREHOUSE_FOLDER`

Observações:

CATALOG_NAME: nome do catálogo do Iceberg.
PROJECT_ID: o ID do projeto do Google Cloud . Os IDs de projetos estão listados na seção Informações do projeto no painel do console do Google Cloud. região em que o cluster está localizado.
LOCATION: um local do BigQuery compatível. O local padrão é "EUA".
BUCKET e WAREHOUSE_FOLDER: bucket e pasta do Cloud Storage usados para o repositório Iceberg.

Clique em Enviar.
Para monitorar o progresso do job e conferir a saída, acesse a página Jobs do Dataproc no console do Google Cloud e clique em Job ID para abrir a página Detalhes do job.
Para conferir os metadados da tabela no BigQuery
1. No Console do Google Cloud, acesse a página BigQuery.
  
  Acessar o BigQuery Studio
2. Acesse os metadados da tabela Iceberg.

REST

É possível usar a API jobs.submit do Dataproc para enviar o job do Spark SQL ao serviço do Dataproc e criar uma tabela do Iceberg com metadados no BigQuery Metastore.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto do Google Cloud . Os IDs dos projetos estão listados na seção Informações do projeto no Painel do console do Google Cloud.
CLUSTER_NAME: o nome do cluster do Dataproc.
REGION: a região do Compute Engine em que o cluster está localizado.
CATALOG_NAME: nome do catálogo do Iceberg.
BUCKET e WAREHOUSE_FOLDER: bucket e pasta do Cloud Storage usados para o repositório Iceberg.

LOCATION

local do BigQuery

jarFileUris: os jars listados são necessários para criar metadados de tabela no BigQuery Metastore.
properties: Propriedades do catálogo.
queryFileUri: o arquivo de job iceberg-table.sql que você copiou para seu bucket no Cloud Storage.

Método HTTP e URL:

POST https://dataproc.googleapis.com/v1/projects/PROJECT_ID/regions/REGION/jobs:submit

Corpo JSON da solicitação:

{
  "projectId": "PROJECT_ID",
  "job": {
    "placement": {
      "clusterName": "CLUSTER_NAME"
    },
    "statusHistory": [],
    "reference": {
      "jobId": "",
      "projectId": "PROJECT_ID"
    },
    "sparkSqlJob": {
      "properties": {
        "spark.sql.catalog."CATALOG_NAME": "org.apache.iceberg.spark.SparkCatalog",
        "spark.sql.catalog."CATALOG_NAME".catalog-impl": "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog",
        "spark.sql.catalog."CATALOG_NAME".gcp_project": "PROJECT_ID",
        "spark.sql.catalog."CATALOG_NAME".gcp_location": "LOCATION",
        "spark.sql.catalog."CATALOG_NAME".warehouse": "gs://BUCKET/WAREHOUSE_FOLDER"
      },
      "jarFileUris": [
        "gs://BUCKET/iceberg-spark-runtime-3.5_2.12-1.5.2.jar,gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar"
      ],
      "scriptVariables": {},
      "queryFileUri": "gs://BUCKET/iceberg-table.sql"
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/regions/REGION/jobs:submit"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/regions/REGION/jobs:submit" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "reference": {
    "projectId": "PROJECT_ID",
    "jobId": "..."
  },
  "placement": {
    "clusterName": "CLUSTER_NAME",
    "clusterUuid": "..."
  },
  "status": {
    "state": "PENDING",
    "stateStartTime": "..."
  },
  "submittedBy": "USER",
  "sparkSqlJob": {
    "queryFileUri": "gs://BUCKET/iceberg-table.sql",
    "properties": {
      "spark.sql.catalog.USER_catalog": "org.apache.iceberg.spark.SparkCatalog",
      "spark.sql.catalog.USER_catalog.catalog-impl": "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog",
      "spark.sql.catalog.USER_catalog.gcp_project": "PROJECT_ID",
      "spark.sql.catalog.USER_catalog.gcp_location": "LOCATION",
      "spark.sql.catalog.USER_catalog.warehouse": "gs://BUCKET/WAREHOUSE_FOLDER"
    },
    "jarFileUris": [
      "gs://BUCKET/iceberg-spark-runtime-3.5_2.12-1.5.2.jar",
      "gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar"
    ]
  },
  "driverControlFilesUri": "gs://dataproc-...",
  "driverOutputResourceUri": "gs://dataproc-.../driveroutput",
  "jobUuid": "...",
  "region": "REGION"
}

Para monitorar o progresso do job e conferir a saída, acesse a página Jobs do Dataproc no console do Google Cloud e clique em Job ID para abrir a página Detalhes do job.

Para conferir os metadados da tabela no BigQuery

No Console do Google Cloud, acesse a página BigQuery.

Acessar o BigQuery Studio
Acessar metadados da tabela Iceberg.

CLI do Spark SQL

As etapas a seguir mostram como criar uma tabela do Iceberg com metadados armazenados no Metastore do BigQuery usando a CLI do Spark SQL em execução no nó mestre de um cluster do Dataproc.

Use o SSH para se conectar ao nó mestre do cluster do Dataproc.

No terminal da sessão SSH, use o editor de texto vi ou nano para copiar os comandos abaixo em um arquivo iceberg-table.sql.

SET CATALOG_NAME = `CATALOG_NAME`;
SET BUCKET = `BUCKET`;
SET WAREHOUSE_FOLDER = `WAREHOUSE_FOLDER`;
USE `${CATALOG_NAME}`;
CREATE NAMESPACE IF NOT EXISTS `${CATALOG_NAME}`.example_namespace;
DROP TABLE IF EXISTS `${CATALOG_NAME}`.example_namespace.example_table;
CREATE TABLE `${CATALOG_NAME}`.example_namespace.example_table (id int, data string) USING ICEBERG LOCATION 'gs://${BUCKET}/${WAREHOUSE_FOLDER}';
INSERT INTO `${CATALOG_NAME}`.example_namespace.example_table VALUES (1, 'first row');
ALTER TABLE `${CATALOG_NAME}`.example_namespace.example_table ADD COLUMNS (newDoubleCol double);
DESCRIBE TABLE `${CATALOG_NAME}`.example_namespace.example_table;

Substitua:

CATALOG_NAME: nome do catálogo do Iceberg.
BUCKET e WAREHOUSE_FOLDER: bucket e pasta do Cloud Storage usados para o repositório Iceberg.

No terminal da sessão SSH, execute o comando spark-sql a seguir para criar a tabela de iceberg.

spark-sql \
--packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.5.2 \
--jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.5.2/iceberg-spark-runtime-3.5_2.12-1.5.2.jar,gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar \
--conf spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog \
--conf spark.sql.catalog.CATALOG_NAME.catalog-impl=org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog \
--conf spark.sql.catalog.CATALOG_NAME.gcp_project=PROJECT_ID \
--conf spark.sql.catalog.CATALOG_NAME.gcp_location=LOCATION \
--conf spark.sql.catalog.CATALOG_NAME.warehouse=gs://BUCKET/WAREHOUSE_FOLDER \
-f iceberg-table.sql

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud . Os IDs dos projetos estão listados na seção Informações do projeto no Painel do console do Google Cloud.
LOCATION: um local do BigQuery compatível. O local padrão é "EUA".

Conferir metadados de tabela no BigQuery
1. No Console do Google Cloud, acesse a página BigQuery.
  
  Acessar o BigQuery Studio
2. Acessar metadados da tabela Iceberg.

Interface da Web do Zeppelin

As etapas a seguir mostram como criar uma tabela do Iceberg com metadados armazenados no BigQuery Metastore usando a interface da Web do Zeppelin em execução no nó mestre de um cluster do Dataproc .

No console do Google Cloud, acesse a página Clusters do Dataproc.

Acesse a página Clusters do Dataproc
Selecione o nome do cluster para abrir a página Detalhes do cluster.
Clique na guia Interfaces da Web para mostrar uma lista de links do Gateway de componentes para as interfaces da Web dos componentes padrão e opcionais instalados no cluster.
Clique no link Zeppelin para abrir a interface da Web do Zeppelin.
Na interface da Web do Zeppelin, clique no menu anônimo e em Intérprete para abrir a página Intérpretes.
Adicione dois frascos ao intérprete do Zeppelin Spark da seguinte maneira:
1. Digite "Spark" na caixa Search interpreters para rolar até a seção do interpretador Spark.
2. Clique em edit.
3. Cole o seguinte no campo spark.jars:
```
https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.5.2/iceberg-spark-runtime-3.5_2.12-1.5.2.jar,gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.5.2-1.0.0-beta.jar
```
4. Clique em Salvar na parte de baixo da seção do interpretador do Spark e, em seguida, clique em OK para atualizar o interpretador e reiniciá-lo com as novas configurações.
No menu do notebook do Zeppelin, clique em Criar nova nota.
Na caixa de diálogo Create new note, insira um nome para o notebook e aceite o interpretador spark padrão. Clique em Criar para abrir o notebook.

Copie o código PySpark abaixo no seu notebook do Zeppelin depois de preencher as variáveis.

%pyspark

from pyspark.sql import SparkSession

project_id = "PROJECT_ID"
catalog = "CATALOG_NAME"
namespace = "NAMESPACE"
location = "LOCATION"
warehouse_dir = "gs://BUCKET/WAREHOUSE_DIRECTORY"

spark = SparkSession.builder \
.appName("BigQuery Metastore Iceberg") \
.config(f"spark.sql.catalog.{catalog}", "org.apache.iceberg.spark.SparkCatalog") \
.config(f"spark.sql.catalog.{catalog}.catalog-impl", "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog") \
.config(f"spark.sql.catalog.{catalog}.gcp_project", f"{project_id}") \
.config(f"spark.sql.catalog.{catalog}.gcp_location", f"{location}") \
.config(f"spark.sql.catalog.{catalog}.warehouse", f"{warehouse_dir}") \
.getOrCreate()

spark.sql(f"USE `{catalog}`;")
spark.sql(f"CREATE NAMESPACE IF NOT EXISTS `{namespace}`;")
spark.sql(f"USE `{namespace}`;")

\# Create table and display schema (without LOCATION)
spark.sql("DROP TABLE IF EXISTS example_iceberg_table")
spark.sql("CREATE TABLE example_iceberg_table (id int, data string) USING ICEBERG")
spark.sql("DESCRIBE example_iceberg_table;")

\# Insert table data.
spark.sql("INSERT INTO example_iceberg_table VALUES (1, 'first row');")

\# Alter table, then display schema. 
spark.sql("ALTER TABLE example_iceberg_table ADD COLUMNS (newDoubleCol double);")

\# Select and display the contents of the table.
spark.sql("SELECT * FROM example_iceberg_table").show()

Substitua:

PROJECT_ID: o ID do projeto do Google Cloud . Os IDs dos projetos estão listados na seção Informações do projeto no Painel do console do Google Cloud.
CATALOG_NAME e NAMESPACE: o nome do catálogo e o namespace do Iceberg se combinam para identificar a tabela Iceberg (catalog.namespace.table_name).
LOCATION: um local do BigQuery compatível. O local padrão é "EUA".
BUCKET e WAREHOUSE_DIRECTORY: bucket e pasta do Cloud Storage usados como diretório do repositório do Iceberg.

Clique no ícone de execução ou pressione Shift-Enter para executar o código. Quando o job é concluído, a mensagem de status mostra "Spark Job Finished", e a saída mostra o conteúdo da tabela:
Conferir metadados de tabela no BigQuery
1. No Console do Google Cloud, acesse a página BigQuery.
  
  Acessar o BigQuery Studio
2. Acessar metadados da tabela Iceberg.