Creare una tabella Apache Iceberg con metadati in BigQuery Metastore

Questo documento illustra come creare una tabella Apache Iceberg con metadati in BigQuery Metastore utilizzando il servizio Dataproc Jobs, la CLI Spark SQL o l'interfaccia web Zeppelin in esecuzione su un cluster Dataproc.

Prima di iniziare

Se non l'hai ancora fatto, crea un progetto Google Cloud , un bucket Cloud Storage e un cluster Dataproc.

  1. Configurare il progetto

    1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

    2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    3. Make sure that billing is enabled for your Google Cloud project.

    4. Enable the Dataproc, BigQuery, and Cloud Storage APIs.

      Enable the APIs

    5. Install the Google Cloud CLI.

    6. To initialize the gcloud CLI, run the following command: 

      gcloud init

    7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

      Go to project selector

    8. Make sure that billing is enabled for your Google Cloud project.

    9. Enable the Dataproc, BigQuery, and Cloud Storage APIs.

      Enable the APIs

    10. Install the Google Cloud CLI.

    11. To initialize the gcloud CLI, run the following command: 

      gcloud init

  2. Crea un bucket Cloud Storage nel tuo progetto.

    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.

  3. Crea un cluster Dataproc. Per risparmiare risorse e costi, puoi creare un cluster Dataproc a un solo nodo per eseguire gli esempi presentati in questo documento.

    • Nella subnet della regione in cui viene creato il cluster deve essere attivo l'accesso privato Google (PGA).

    • Se vuoi eseguire l'esempio di interfaccia web di Zeppelin in questa guida, devi utilizzare o creare un cluster Dataproc con il componente facoltativo Zeppelin abilitato.

  4. Concedi i ruoli a un account di servizio personalizzato (se necessario): per impostazione predefinita, le VM del cluster Dataproc utilizzano l'account di servizio predefinito di Compute Engine per interagire con Dataproc. Se vuoi specificare un account di servizio personalizzato quando crei il cluster, questo deve disporre del ruolo Ruolo utente Dataproc (roles/dataproc.worker) o di un ruolo personalizzato con le autorizzazioni necessarie per il ruolo utente.

Mappatura del database OSS al set di dati BigQuery

Tieni presente la seguente mappatura tra i termini del database open source e del set di dati BigQuery:

Database OSS Set di dati BigQuery
Spazio dei nomi, Database Set di dati
Tabella partizionata o non partizionata Tabella
Visualizza Visualizza

Creare una tabella Iceberg

Questa sezione mostra come creare una tabella Iceberg con metadati in BigQuery Metastore inviando un codice Spark SQL al servizio Dataproc, alla CLI Spark SQL, e all'interfaccia web del componente Zeppelin, che vengono eseguiti su un cluster Dataproc.

Job Dataproc

Puoi inviare un job al servizio Dataproc inviandolo a un cluster Dataproc utilizzando la console Google Cloud o Google Cloud CLI oppure tramite una richiesta REST HTTP o una chiamata programmatica gRPC Dataproc Cloud Client Libraries all'API Dataproc Jobs.

Gli esempi in questa sezione mostrano come inviare un job Dataproc SQL al servizio Dataproc per creare una tabella Iceberg con metadati in BigQuery utilizzando la gcloud CLI, la console Google Cloud o l'API REST Dataproc.

Prepara i file di job

Esegui i seguenti passaggi per creare un file di job Spark SQL. Il file contiene comandi Spark SQL per creare e aggiornare una tabella Iceberg.

  1. In una finestra del terminale locale o in Cloud Shell, utilizza un editor di testo, come vi o nano, per copiare i comandi riportati di seguito in un file iceberg-table.sql, quindi salva il file nella directory corrente.

    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;

    Sostituisci quanto segue:

    • CATALOG_NAME: nome del catalogo Iceberg.
    • BUCKET e WAREHOUSE_FOLDER: bucket e cartella Cloud Storage utilizzati per il magazzino Iceberg.

  2. Utilizza lo strumento gsutil per copiare il file iceberg-table.sql locale nel tuo bucket in Cloud Storage.

    gsutil cp iceberg-table.sql gs://BUCKET/

Quindi, scarica e copia il file JAR iceberg-spark-runtime-3.5_2.12-1.5.2 in Cloud Storage.

  1. In una finestra del terminale locale o in Cloud Shell, esegui il seguente comando curl per scaricare il file JAR iceberg-spark-runtime-3.5_2.12-1.5.2 nella directory corrente.

    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

  2. Utilizza lo strumento gsutil per copiare il file JAR iceberg-spark-runtime-3.5_2.12-1.5.2 locale dalla directory corrente al tuo bucket in Cloud Storage.

    gsutil cp iceberg-spark-runtime-3.5_2.12-1.5.2.jar gs://BUCKET/

Invia il job Spark SQL

Seleziona una scheda per seguire le istruzioni per inviare il job Spark SQL al servizio Dataproc utilizzando gcloud CLI, la console Google Cloud o l'API REST Dataproc.

gcloud

  1. Esegui il seguente comando gcloud dataproc jobs submit spark-sql localmente in una finestra del terminale locale o in Cloud Shell per inviare il job Spark SQL per creare la tabella 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"

    Note:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud . Gli ID progetto sono elencati nella sezione Informazioni sul progetto della Dashboard della console Google Cloud.
    • CLUSTER_NAME: il nome del cluster Dataproc.
    • REGION: la regione Compute Engine in cui si trova il cluster.
    • CATALOG_NAME: nome del catalogo Iceberg.
    • BUCKET e WAREHOUSE_FOLDER: bucket e cartella Cloud Storage utilizzati per il magazzino Iceberg.
    • LOCATION: una posizione BigQuery supportata. La località predefinita è "US".
    • --jars: i jar elencati sono necessari per creare i metadati delle tabelle in BigQuery Metastore.
    • --properties: Proprietà del catalogo.
    • -f: il file di job iceberg-table.sql che hai copiato nel tuo bucket in Cloud Storage.

  2. Visualizza la descrizione della tabella nell'output del terminale al termine del job.

    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.

  3. Per visualizzare i metadati della tabella in BigQuery

    1. Nella console Google Cloud, vai alla pagina BigQuery.

      Vai a BigQuery Studio

    2. Visualizza i metadati della tabella Iceberg.

Console

Esegui i seguenti passaggi per utilizzare la console Google Cloud per inviare il job Spark SQL al servizio Dataproc al fine di creare una tabella Iceberg con metadati in BigQuery Metastore.

  1. Nella console Google Cloud, vai a Invia un job in Dataproc.

    Vai alla pagina Invia un job e completa i seguenti campi:

    • ID job: accetta l'ID suggerito o inserisci il tuo ID.
    • Regione: seleziona la regione in cui si trova il cluster.
    • Cluster: seleziona il cluster.
    • Tipo di job: seleziona SparkSql.
    • Tipo di origine query: seleziona Query file.
    • File di query: inserisci gs://BUCKET/iceberg-table.sql
    • File jar: inserisci quanto segue: 
      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
    • Proprietà: fai clic cinque volte su Aggiungi proprietà per creare un elenco di cinque campi di immissione key value, quindi copia le seguenti coppie Chiave e Valore per definire cinque proprietà.
      # Chiave Valore
      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

    Note:

    • CATALOG_NAME: nome del catalogo Iceberg.
    • PROJECT_ID: l'ID del tuo progetto Google Cloud . Gli ID progetto sono elencati nella sezione Informazioni sul progetto della dashboard di Google Cloud Console. regione in cui si trova il tuo cluster.
    • LOCATION: una posizione BigQuery supportata. La località predefinita è "US".
    • BUCKET e WAREHOUSE_FOLDER: bucket e cartella Cloud Storage utilizzati per il magazzino Iceberg.

  2. Fai clic su Invia.

  3. Per monitorare l'avanzamento del job e visualizzarne l'output, vai alla pagina Dataproc Job nella console Google Cloud, poi fai clic su Job ID per aprire la pagina Dettagli job.

  4. Per visualizzare i metadati della tabella in BigQuery

    1. Nella console Google Cloud, vai alla pagina BigQuery.

      Vai a BigQuery Studio

    2. Visualizza i metadati della tabella Iceberg.

REST

Puoi utilizzare l'API Dataproc jobs.submit per inviare il job Spark SQL al servizio Dataproc per creare una tabella Iceberg con metadati nel metastore BigQuery.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_ID: l'ID del tuo progetto Google Cloud . Gli ID progetto sono elencati nella sezione Informazioni sul progetto della Dashboard della console Google Cloud.
  • CLUSTER_NAME: il nome del cluster Dataproc.
  • REGION: l'area geografica di Compute Engine in cui si trova il cluster.
  • CATALOG_NAME: nome del catalogo Iceberg.
  • BUCKET e WAREHOUSE_FOLDER: bucket Cloud Storage e cartella utilizzati per il magazzino Iceberg.
    • LOCATION: una posizione BigQuery supportata. La località predefinita è "US".
  • jarFileUris: i file JAR elencati sono necessari per creare i metadati delle tabelle in BigQuery Metastore.
  • properties: Proprietà del catalogo.
  • queryFileUri: il file di job iceberg-table.sql che hai copiato nel tuo bucket in Cloud Storage.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

{
  "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"
    }
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "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"
}

Per monitorare l'avanzamento del job e visualizzarne l'output, vai alla pagina Dataproc Job nella console Google Cloud, poi fai clic su Job ID per aprire la pagina Dettagli job.

Per visualizzare i metadati della tabella in BigQuery

  1. Nella console Google Cloud, vai alla pagina BigQuery.

    Vai a BigQuery Studio

  2. Visualizza i metadati della tabella Iceberg.

Interfaccia a riga di comando Spark SQL

I passaggi riportati di seguito mostrano come creare una tabella Iceberg con i metadati della tabella memorizzati nel metastore BigQuery utilizzando la CLI Spark SQL in esecuzione sul nodo principale di un cluster Dataproc.

  1. Utilizza SSH per connetterti al nodo master del tuo cluster Dataproc.

  2. Nel terminale della sessione SSH, utilizza l'editor di testo vi o nano per copiare i seguenti comandi in un file 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;

    Sostituisci quanto segue:

    • CATALOG_NAME: nome del catalogo Iceberg.
    • BUCKET e WAREHOUSE_FOLDER: bucket e cartella Cloud Storage utilizzati per il magazzino Iceberg.

  3. Nel terminale della sessione SSH, esegui il seguente comando spark-sql per creare la tabella 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

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud . Gli ID progetto sono elencati nella sezione Informazioni sul progetto della dashboard della console Google Cloud.
    • LOCATION: una posizione BigQuery supportata. La località predefinita è "US".

  4. Visualizzare i metadati della tabella in BigQuery

    1. Nella console Google Cloud, vai alla pagina BigQuery.

      Vai a BigQuery Studio

    2. Visualizza i metadati della tabella Iceberg.

Interfaccia web di Zeppelin

I passaggi riportati di seguito mostrano come creare una tabella Iceberg con i metadati della tabella archiviati in BigQuery Metastore utilizzando l'interfaccia web di Zeppelin in esecuzione sul nodo principale di un cluster Dataproc .

  1. Nella console Google Cloud, vai alla pagina Cluster di Dataproc.

    Vai alla pagina Cluster Dataproc

  2. Seleziona il nome del cluster per aprire la pagina Dettagli cluster.

  3. Fai clic sulla scheda Interfacce web per visualizzare un elenco di link al gateway dei componenti alle interfacce web dei componenti predefiniti e facoltativi installati sul cluster.

  4. Fai clic sul link Zeppelin per aprire l'interfaccia web di Zeppelin.

  5. Nell'interfaccia web di Zeppelin, fai clic sul menu Anonimo e poi su Interprete per aprire la pagina Interpreti.

  6. Aggiungi due jar all'interprete Zeppelin Spark, come segue:

    1. Digita "Spark" nella casella Search interpreters per scorrere fino alla sezione dell'interprete Spark.
    2. Fai clic su edit (modifica).

    3. Incolla quanto segue nel 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. Fai clic su Salva nella parte inferiore della sezione dell'interprete Spark, quindi su OK per aggiornare l'interprete e riavviarlo con le nuove impostazioni.

  7. Nel menu del blocco note Zeppelin, fai clic su Crea nuova nota.

  8. Nella finestra di dialogo Crea nuova nota, inserisci un nome per il blocco note e accetta l'interprete spark predefinito. Fai clic su Crea per aprire il notebook.

  9. Copia il seguente codice PySpark nel tuo notebook Zeppelin dopo aver compilato le variabili.

    %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()

    Sostituisci quanto segue:

    • PROJECT_ID: l'ID del tuo progetto Google Cloud . Gli ID progetto sono elencati nella sezione Informazioni sul progetto della Dashboard della console Google Cloud.
    • CATALOG_NAME e NAMESPACE: il nome e il namespace del catalogo Iceberg si combinano per identificare la tabella Iceberg (catalog.namespace.table_name).
    • LOCATION: una posizione BigQuery supportata. La località predefinita è "US".
    • BUCKET e WAREHOUSE_DIRECTORY: bucket e cartella Cloud Storage utilizzati come directory del magazzino Iceberg.

  10. Fai clic sull'icona di esecuzione o premi Shift-Enter per eseguire il codice. Al termine del job, viene visualizzato il messaggio di stato "Job Spark completato" e l'output mostra i contenuti della tabella:

  11. Visualizzare i metadati della tabella in BigQuery

    1. Nella console Google Cloud, vai alla pagina BigQuery.

      Vai a BigQuery Studio

    2. Visualizza i metadati della tabella Iceberg.