Configurar o catálogo de ambiente de execução do Lakehouse para o Serviço Gerenciado para Apache Spark usando o Apache Iceberg 1.9

Apache Spark

1. Configure um novo cluster. Para criar um cluster do Serviço Gerenciado para Apache Spark, execute o seguinte comando gcloud dataproc clusters create, que contém as configurações necessárias para usar o catálogo de tempo de execução do Lakehouse:

   gcloud dataproc clusters create CLUSTER_NAME \
       --project=PROJECT_ID \
       --region=LOCATION \
       --single-node

   Substitua:

   • CLUSTER_NAME: um nome para seu cluster do Serviço Gerenciado para Apache Spark.
   • PROJECT_ID: o ID do Google Cloud projeto em que você está criando o cluster.
   • LOCATION: a região do Compute Engine em que você está criando o cluster.

2. Envie um job do Apache Spark usando um dos seguintes métodos:

   CLI do Google Cloud

   gcloud dataproc jobs submit spark-sql \
     --project=PROJECT_ID \
     --cluster=CLUSTER_NAME \
     --region=REGION \
     --jars=https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.6.1/iceberg-spark-runtime-3.5_2.12-1.6.1.jar,BIGLAKE_ICEBERG_CATALOG_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=WAREHOUSE_DIRECTORY \
     --execute="SPARK_SQL_COMMAND"

   Substitua:

   • PROJECT_ID: o ID do Google Cloud projeto que contém o cluster do Serviço Gerenciado para Apache Spark.
   • CLUSTER_NAME: o nome do cluster do Serviço Gerenciado para Apache Spark que você está usando para executar o job do Apache Spark SQL.
   • REGION: a região do Compute Engine em que o cluster está localizado.
   • BIGLAKE_ICEBERG_CATALOG_JAR: o URI do Cloud Storage do plug-in de catálogo personalizado do Apache Iceberg a ser usado. Dependendo do número da versão do Apache Iceberg, selecione uma das seguintes opções:
     • Apache Iceberg 1.9.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.9.1-1.0.1.jar
     • Apache Iceberg 1.6.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.6.1-1.0.2.jar
   • LOCATION: o local dos recursos do BigQuery.
   • CATALOG_NAME: o nome do catálogo do Apache Spark a ser usado com seu job do SQL.
   • WAREHOUSE_DIRECTORY: a pasta do Cloud Storage que contém seu data warehouse. Esse valor começa com gs://.
   • SPARK_SQL_COMMAND: a consulta SQL do Apache Spark que você quer executar. Essa consulta inclui os comandos para criar seus recursos. Por exemplo, para criar um namespace e uma tabela.

   CLI do spark-sql

   1. No console do Google Cloud , acesse a página Instâncias de VM.

      Acessar instâncias de VM

   2. Para se conectar a uma instância de VM do Serviço Gerenciado para Apache Spark, clique em SSH na linha que lista o nome da instância de VM principal do cluster do Serviço Gerenciado para Apache Spark, que é o nome do cluster seguido por um sufixo -m. O resultado será o seguinte:

      Connected, host fingerprint: ssh-rsa ...
      Linux cluster-1-m 3.16.0-0.bpo.4-amd64 ...
      ...
      example-cluster@cluster-1-m:~$
      

   3. No terminal, execute o seguinte comando de inicialização para o catálogo de tempo de execução do Lakehouse:

      spark-sql \
        --jars https://storage-download.googleapis.com/maven-central/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.6.1/iceberg-spark-runtime-3.5_2.12-1.6.1.jar,BIGLAKE_ICEBERG_CATALOG_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=WAREHOUSE_DIRECTORY

   Substitua:

   • BIGLAKE_ICEBERG_CATALOG_JAR: o URI do Cloud Storage do plug-in de catálogo personalizado do Apache Iceberg a ser usado. Dependendo do número da versão do Apache Iceberg, selecione uma das seguintes opções:
     • Apache Iceberg 1.9.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.9.1-1.0.1.jar
     • Apache Iceberg 1.6.1: gs://spark-lib/bigquery/iceberg-bigquery-catalog-1.6.1-1.0.2.jar
   • CATALOG_NAME: o nome do catálogo do Apache Spark que você está usando com seu job do SQL.
   • PROJECT_ID: o ID do projeto Google Cloud do catálogo de tempo de execução do Lakehouse ao qual seu catálogo do Apache Spark está vinculado.
   • LOCATION: o Google Cloud local do catálogo de ambientes de execução do Lakehouse.
   • WAREHOUSE_DIRECTORY: a pasta do Cloud Storage que contém seu data warehouse. Esse valor começa com gs://.

   Depois de se conectar ao cluster, o terminal do Apache Spark vai mostrar o prompt spark-sql, que pode ser usado para enviar jobs do Apache Spark.

     spark-sql (default)>
   

Apache Flink

1. Crie um cluster do Serviço Gerenciado para Apache Spark com o componente opcional do Apache Flink ativado e verifique se você está usando o Serviço Gerenciado para Apache Spark 2.2 ou uma versão mais recente.

2. No console do Google Cloud , acesse a página Instâncias de VM.

   Acessar instâncias de VM

3. Na lista de instâncias de máquina virtual, clique em SSH para se conectar à instância de VM do cluster principal do Serviço Gerenciado para Apache Spark, que aparece como o nome do cluster seguido por um sufixo -m.

4. Configure o catálogo personalizado do Apache Iceberg para o plug-in do BigQuery no catálogo do ambiente de execução do Lakehouse:

   FLINK_VERSION=1.19
   ICEBERG_VERSION=1.6.1
   
   cd /usr/lib/flink
   
   sudo wget -c https://repo.maven.apache.org/maven2/org/apache/iceberg/iceberg-flink-runtime-${FLINK_VERSION}/${ICEBERG_VERSION}/iceberg-flink-runtime-${FLINK_VERSION}-${ICEBERG_VERSION}.jar -P lib
   
   sudo gcloud storage cp gs://spark-lib/bigquery/iceberg-bigquery-catalog-${ICEBERG_VERSION}-1.0.2.jar lib/

5. Inicie a sessão do Apache Flink no YARN:

   HADOOP_CLASSPATH=`hadoop classpath`
   
   sudo bin/yarn-session.sh -nm flink-dataproc -d
   
   sudo bin/sql-client.sh embedded \
   -s yarn-session

6. Crie um catálogo no Apache Flink:

   CREATE CATALOG CATALOG_NAME WITH (
   'type'='iceberg',
   'warehouse'='WAREHOUSE_DIRECTORY',
   'catalog-impl'='org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog',
   'gcp_project'='PROJECT_ID',
   'gcp_location'='LOCATION'
   );

   Substitua:

   • CATALOG_NAME: o identificador do catálogo do Apache Flink, que está vinculado ao catálogo do ambiente de execução do Lakehouse.
   • WAREHOUSE_DIRECTORY: o caminho base para o diretório do data warehouse (a pasta do Cloud Storage em que o Apache Flink cria arquivos). Esse valor começa com gs://.
   • PROJECT_ID: o ID do projeto do catálogo de tempo de execução do Lakehouse ao qual o catálogo do Apache Flink está vinculado.
   • LOCATION: o local dos recursos do BigQuery.

Sua sessão do Apache Flink agora está conectada ao catálogo de ambientes de execução do Lakehouse, e você pode executar comandos SQL do Apache Flink.

Gerenciar recursos do catálogo de ambientes de execução do Lakehouse

Agora que você está conectado ao catálogo do ambiente de execução do Lakehouse, é possível criar e visualizar recursos com base nos metadados armazenados nele.

Por exemplo, execute os comandos a seguir na sua sessão interativa do Apache Flink SQL para criar um banco de dados e uma tabela do Apache Iceberg.

1. Use o catálogo personalizado do Apache Iceberg para BigQuery:

   USE CATALOG CATALOG_NAME;

   Substitua CATALOG_NAME pelo identificador do catálogo do Apache Flink.

2. Crie um banco de dados, que cria um conjunto de dados no BigQuery:

   CREATE DATABASE IF NOT EXISTS DATABASE_NAME;

   Substitua DATABASE_NAME pelo nome do novo banco de dados.

3. Use o banco de dados que você criou:

   USE DATABASE_NAME;

4. Crie uma tabela do Apache Iceberg. O comando a seguir cria uma tabela de vendas de exemplo:

   CREATE TABLE IF NOT EXISTS ICEBERG_TABLE_NAME (
     order_number BIGINT,
     price        DECIMAL(32,2),
     buyer        ROW<first_name STRING, last_name STRING>,
     order_time   TIMESTAMP(3)
   );

   Substitua ICEBERG_TABLE_NAME por um nome para a nova tabela.

5. Ver metadados da tabela:

   DESCRIBE EXTENDED ICEBERG_TABLE_NAME;

6. Liste as tabelas no banco de dados:

   SHOW TABLES;

Ingerir dados na tabela

Depois de criar uma tabela do Apache Iceberg na seção anterior, use o Apache Flink DataGen como uma fonte de dados para ingerir dados em tempo real na tabela. As etapas a seguir são um exemplo desse fluxo de trabalho:

1. Crie uma tabela temporária usando o DataGen:

   CREATE TEMPORARY TABLE DATABASE_NAME.TEMP_TABLE_NAME
   WITH (
     'connector' = 'datagen',
     'rows-per-second' = '10',
     'fields.order_number.kind' = 'sequence',
     'fields.order_number.start' = '1',
     'fields.order_number.end' = '1000000',
     'fields.price.min' = '0',
     'fields.price.max' = '10000',
     'fields.buyer.first_name.length' = '10',
     'fields.buyer.last_name.length' = '10'
   )
   LIKE DATABASE_NAME.ICEBERG_TABLE_NAME (EXCLUDING ALL);

   Substitua:

   • DATABASE_NAME: o nome do banco de dados para armazenar sua tabela temporária.
   • TEMP_TABLE_NAME: um nome para sua tabela temporária.
   • ICEBERG_TABLE_NAME: o nome da tabela do Apache Iceberg que você criou na seção anterior.

2. Defina o paralelismo como 1:

   SET 'parallelism.default' = '1';

3. Defina o intervalo de checkpoint:

   SET 'execution.checkpointing.interval' = '10second';

4. Defina o checkpoint:

   SET 'state.checkpoints.dir' = 'hdfs:///flink/checkpoints';

5. Inicie o job de transmissão em tempo real:

   INSERT INTO ICEBERG_TABLE_NAME SELECT * FROM TEMP_TABLE_NAME;

   O resultado será o seguinte:

   [INFO] Submitting SQL update statement to the cluster...
   [INFO] SQL update statement has been successfully submitted to the cluster:
   Job ID: 0de23327237ad8a811d37748acd9c10b
   

6. Para verificar o status do job de streaming, faça o seguinte:

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

      Acessar Clusters

   2. Selecione o cluster.

   3. Clique na guia Interfaces da Web.

   4. Clique no link YARN ResourceManager.

   5. Na interface do YARN ResourceManager, encontre sua sessão do Apache Flink e clique no link ApplicationMaster em IU de rastreamento.

   6. Na coluna Status, confirme se o status do job é Em execução.

7. Consultar dados de streaming no cliente SQL do Apache Flink:

   SELECT * FROM ICEBERG_TABLE_NAME
   /*+ OPTIONS('streaming'='true', 'monitor-interval'='3s')*/
   ORDER BY order_time desc
   LIMIT 20;

8. Consultar dados de streaming no BigQuery:

   SELECT * FROM `DATABASE_NAME.ICEBERG_TABLE_NAME`
   ORDER BY order_time desc
   LIMIT 20;

9. Encerre o job de streaming no cliente SQL do Apache Flink:

   STOP JOB 'JOB_ID';

   Substitua JOB_ID pelo ID do job que foi exibido na saída quando você criou o job de streaming.

SQL do Apache Spark

1. Crie um arquivo SQL com os comandos do Apache Spark SQL que você quer executar no catálogo do ambiente de execução do Lakehouse. Por exemplo, este comando cria um namespace e uma tabela:

   CREATE NAMESPACE `CATALOG_NAME`.NAMESPACE_NAME;
   CREATE TABLE `CATALOG_NAME`.NAMESPACE_NAME.TABLE_NAME (id int, data string) USING ICEBERG LOCATION 'WAREHOUSE_DIRECTORY';

   Substitua:

   • CATALOG_NAME: o nome do catálogo que faz referência à sua tabela do Apache Spark.
   • NAMESPACE_NAME: o nome do namespace que referencia sua tabela do Apache Spark.
   • TABLE_NAME: um nome para sua tabela do Apache Spark.
   • WAREHOUSE_DIRECTORY: o URI da pasta do Cloud Storage em que seu data warehouse está armazenado.

2. Envie um job em lote do Apache Spark SQL executando o seguinte comando gcloud dataproc batches submit spark-sql:

   gcloud dataproc batches submit spark-sql SQL_SCRIPT_PATH \
       --project=PROJECT_ID \
       --region=REGION \
       --subnet=projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
       --deps-bucket=BUCKET_PATH \
       --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=WAREHOUSE_DIRECTORY"

   Substitua:

   • SQL_SCRIPT_PATH: o caminho para o arquivo SQL que o job em lote usa.
   • PROJECT_ID: o ID do Google Cloud projeto em que o job em lote será executado.
   • REGION: a região em que sua carga de trabalho é executada.
   • SUBNET_NAME (opcional): o nome de uma sub-rede VPC no REGION que atende aos requisitos de sub-rede da sessão.
   • BUCKET_PATH: o local do bucket do Cloud Storage para fazer upload das dependências da carga de trabalho. O WAREHOUSE_DIRECTORY está localizado neste bucket. O prefixo de URI gs:// do bucket não é necessário. É possível especificar o caminho ou o nome do bucket, por exemplo, mybucketname1.
   • LOCATION: o local para executar o job em lote.

   Para mais informações sobre como enviar jobs em lote do Apache Spark, consulte Executar uma carga de trabalho em lote do Apache Spark.

PySpark

1. Crie um arquivo Python com os comandos do PySpark que você quer executar no catálogo do ambiente de execução do Lakehouse.

   Por exemplo, o comando a seguir configura um ambiente do Apache Spark para interagir com tabelas do Apache Iceberg armazenadas no catálogo do ambiente de execução do Lakehouse. Em seguida, o comando cria um novo namespace e uma tabela do Apache Iceberg dentro desse namespace.

   from pyspark.sql import SparkSession
   
   spark = SparkSession.builder \
   .appName("Lakehouse runtime catalog Iceberg") \
   .config("spark.sql.catalog.CATALOG_NAME", "org.apache.iceberg.spark.SparkCatalog") \
   .config("spark.sql.catalog.CATALOG_NAME.catalog-impl", "org.apache.iceberg.gcp.bigquery.BigQueryMetastoreCatalog") \
   .config("spark.sql.catalog.CATALOG_NAME.gcp_project", "PROJECT_ID") \
   .config("spark.sql.catalog.CATALOG_NAME.gcp_location", "LOCATION") \
   .config("spark.sql.catalog.CATALOG_NAME.warehouse", "WAREHOUSE_DIRECTORY") \
   .getOrCreate()
   
   spark.sql("USE `CATALOG_NAME`;")
   spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME;")
   spark.sql("USE NAMESPACE_NAME;")
   spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG LOCATION 'WAREHOUSE_DIRECTORY';")

   Substitua:

   • PROJECT_ID: o ID do Google Cloud projeto em que o job em lote será executado.
   • LOCATION: o local em que os recursos do BigQuery estão localizados.
   • CATALOG_NAME: o nome do catálogo que faz referência à sua tabela do Apache Spark.
   • TABLE_NAME: um nome para sua tabela do Apache Spark.
   • WAREHOUSE_DIRECTORY: o URI da pasta do Cloud Storage em que seu data warehouse está armazenado.
   • NAMESPACE_NAME: o nome do namespace que referencia sua tabela do Apache Spark.

2. Envie o job em lote usando o seguinte comando gcloud dataproc batches submit pyspark:

   gcloud dataproc batches submit pyspark PYTHON_SCRIPT_PATH \
       --version=2.2 \
       --project=PROJECT_ID \
       --region=REGION \
       --deps-bucket=BUCKET_PATH \
       --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=WAREHOUSE_DIRECTORY"

   Substitua:

   • PYTHON_SCRIPT_PATH: o caminho para o script Python usado pelo job em lote.
   • PROJECT_ID: o ID do Google Cloud projeto em que o job em lote será executado.
   • REGION: a região em que sua carga de trabalho é executada.
   • BUCKET_PATH: o local do bucket do Cloud Storage para fazer upload das dependências da carga de trabalho. O prefixo de URI gs:// do bucket não é necessário. É possível especificar o caminho ou o nome do bucket, por exemplo, mybucketname1.

   Para mais informações sobre como enviar jobs em lote do PySpark, consulte a referência da gcloud do PySpark.