Ce document explique comment créer une table Apache Iceberg avec des métadonnées dans BigQuery Metastore à l'aide du service Dataproc Jobs, de la CLI Spark SQL ou de l'interface Web Zeppelin exécutée sur un cluster Dataproc.
Avant de commencer
Si ce n'est pas déjà fait, créez un projet Google Cloud , un bucket Cloud Storage et un cluster Dataproc.
Configurer votre projet
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Dataproc, BigQuery, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Dataproc, BigQuery, and Cloud Storage APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
Créez un bucket Cloud Storage dans votre projet.
- In the Google Cloud console, go to the Cloud Storage Buckets page.
- Click Create bucket.
- 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.
- Click Create.
En créant un cluster Dataproc. Pour économiser des ressources et des coûts, vous pouvez créer un cluster Dataproc à nœud unique pour exécuter les exemples présentés dans ce document.
L'accès privé à Google (PGA) doit être activé sur le sous-réseau de la région dans laquelle le cluster est créé.
Si vous souhaitez exécuter l'exemple d'interface Web Zeppelin dans ce guide, vous devez utiliser ou créer un cluster Dataproc avec le composant Zeppelin facultatif activé.
Attribuez des rôles à un compte de service personnalisé (si nécessaire): par défaut, les VM de cluster Dataproc utilisent le compte de service Compute Engine par défaut pour interagir avec Dataproc. Si vous souhaitez spécifier un compte de service personnalisé lorsque vous créez votre cluster, il doit disposer du rôle Nœud de calcul Dataproc (
roles/dataproc.worker
) ou d'un rôle personnalisé avec les autorisations de nœud de calcul requises.
Mappage de la base de données OSS sur l'ensemble de données BigQuery
Notez le mappage suivant entre les termes de base de données Open Source et de jeu de données BigQuery:
Base de données OSS | Ensemble de données BigQuery |
---|---|
Espace de noms, base de données | Ensemble de données |
Table partitionnée ou non | Tableau |
Afficher | Afficher |
Créer une table Iceberg
Cette section explique comment créer une table Iceberg avec des métadonnées dans BigQuery Metastore en envoyant un code Spark SQL au service Dataproc, à la CLI Spark SQL et à l'interface Web du composant Zeppelin, qui s'exécutent sur un cluster Dataproc.
Tâche Dataproc
Vous pouvez envoyer une tâche au service Dataproc en l'envoyant à un cluster Dataproc à l'aide de la console Google Cloud ou de la CLI Google Cloud, ou via une requête REST HTTP ou un appel gRPC programmatique des bibliothèques clientes Cloud Dataproc à l'API Dataproc Jobs.
Les exemples de cette section vous expliquent comment envoyer une tâche Dataproc Spark SQL au service Dataproc pour créer une table Iceberg avec des métadonnées dans BigQuery à l'aide de gcloud CLI, de la console Google Cloud ou de l'API REST Dataproc.
Préparer les fichiers de tâche
Pour créer un fichier de tâche Spark SQL, procédez comme suit : Le fichier contient des commandes Spark SQL permettant de créer et de mettre à jour une table Iceberg.
Dans une fenêtre de terminal locale ou dans Cloud Shell, utilisez un éditeur de texte, tel que
vi
ounano
, pour copier les commandes suivantes dans un fichiericeberg-table.sql
, puis enregistrez le fichier dans le répertoire actuel.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;
Remplacez les éléments suivants :
- CATALOG_NAME: nom du catalogue Iceberg.
- BUCKET et WAREHOUSE_FOLDER: bucket et dossier Cloud Storage utilisés pour l'entrepôt Iceberg.
Utilisez l'outil
gsutil
pour copier leiceberg-table.sql
local dans votre bucket Cloud Storage.gsutil cp iceberg-table.sql gs://BUCKET/
Téléchargez ensuite le fichier JAR iceberg-spark-runtime-3.5_2.12-1.5.2
et copiez-le dans Cloud Storage.
Dans une fenêtre de terminal locale ou dans Cloud Shell, exécutez la commande
curl
suivante pour télécharger le fichier JARiceberg-spark-runtime-3.5_2.12-1.5.2
dans le répertoire actuel.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
Utilisez l'outil
gsutil
pour copier le fichier JARiceberg-spark-runtime-3.5_2.12-1.5.2
local du répertoire actuel vers votre bucket dans Cloud Storage.gsutil cp iceberg-spark-runtime-3.5_2.12-1.5.2.jar gs://BUCKET/
Envoyer la tâche Spark SQL
Sélectionnez un onglet pour suivre les instructions permettant d'envoyer la tâche Spark SQL au service Dataproc à l'aide de la gcloud CLI, de la console Google Cloud ou de l'API REST Dataproc.
gcloud
Exécutez la commande gcloud dataproc jobs submit spark-sql suivante en local dans une fenêtre de terminal ou dans Cloud Shell pour envoyer la tâche Spark SQL afin de créer le tableau 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"
Remarques :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projet sont listés dans la section Project info (Informations sur le projet) du tableau de bord de la console Google Cloud.
- CLUSTER_NAME: nom de votre cluster Dataproc.
- REGION: région Compute Engine dans laquelle se trouve votre cluster.
- CATALOG_NAME: nom du catalogue Iceberg.
- BUCKET et WAREHOUSE_FOLDER: bucket et dossier Cloud Storage utilisés pour l'entrepôt Iceberg.
- LOCATION: emplacement BigQuery compatible. L'emplacement par défaut est "États-Unis".
--jars
: Les fichiers JAR listés sont nécessaires pour créer des métadonnées de table dans BigQuery Metastore.--properties
: Propriétés du catalogue.-f
: fichier de tâcheiceberg-table.sql
que vous avez copié dans votre bucket dans Cloud Storage.
Affichez la description du tableau dans la sortie du terminal une fois la tâche terminée.
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.
Afficher les métadonnées d'une table dans BigQuery
Dans la console Google Cloud, accédez à la page BigQuery.
Afficher les métadonnées de table Iceberg
Console
Suivez les étapes ci-dessous pour envoyer la tâche Spark SQL au service Dataproc à l'aide de la console Google Cloud afin de créer une table Iceberg avec des métadonnées dans BigQuery Metastore.
Dans la console Google Cloud, accédez à Envoyer une tâche dans Dataproc.
Accédez à la page "Envoyer une tâche", puis renseignez les champs suivants:
- ID de tâche: acceptez l'ID suggéré ou saisissez le vôtre.
- Région: sélectionnez la région dans laquelle se trouve votre cluster.
- Cluster (Cluster) : sélectionnez votre cluster.
- Job type (Type de tâche) : sélectionnez
SparkSql
. - Type de source de la requête: sélectionnez
Query file
. - Fichier de requête: insérer
gs://BUCKET/iceberg-table.sql
- Fichiers JAR: insérez ce qui suit:
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
- Propriétés: cliquez cinq fois sur
key
value
, puis copiez les paires Clé et Valeur suivantes pour définir cinq propriétés.# Clé Valeur 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
Ajouter une propriété pour créer une liste de cinq champs de saisie
Remarques :
- CATALOG_NAME: nom du catalogue Iceberg.
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projet sont listés dans la section Project info (Informations sur le projet) du tableau de bord de la console Google Cloud. région où se trouve votre cluster.
- LOCATION: emplacement BigQuery compatible. L'emplacement par défaut est "États-Unis".
- BUCKET et WAREHOUSE_FOLDER: bucket et dossier Cloud Storage utilisés pour l'entrepôt Iceberg.
Cliquez sur Envoyer.
Pour surveiller la progression de la tâche et afficher son résultat, accédez à la page Tâches Dataproc dans la console Google Cloud, puis cliquez sur
Job ID
pour ouvrir la page Détails de la tâche.Afficher les métadonnées d'une table dans BigQuery
Dans la console Google Cloud, accédez à la page BigQuery.
Afficher les métadonnées de table Iceberg
REST
Vous pouvez utiliser l'API Dataproc jobs.submit pour envoyer la tâche SQL Spark au service Dataproc afin de créer une table Iceberg avec des métadonnées dans BigQuery Metastore.
Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projet sont listés dans la section Project info (Informations sur le projet) du tableau de bord de la console Google Cloud.
- CLUSTER_NAME: nom de votre cluster Dataproc.
- REGION: région Compute Engine dans laquelle se trouve votre cluster.
- CATALOG_NAME: nom du catalogue Iceberg.
- BUCKET et WAREHOUSE_FOLDER: bucket et dossier Cloud Storage utilisés pour l'entrepôt Iceberg. LOCATION: emplacement BigQuery compatible. L'emplacement par défaut est "États-Unis".
jarFileUris
: les fichiers JAR listés sont nécessaires pour créer des métadonnées de table dans BigQuery Metastore.properties
: Propriétés du catalogue.queryFileUri
: fichier de tâcheiceberg-table.sql
que vous avez copié dans votre bucket dans Cloud Storage.
Méthode HTTP et URL :
POST https://dataproc.googleapis.com/v1/projects/PROJECT_ID/regions/REGION/jobs:submit
Corps JSON de la requête :
{ "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" } } }
Pour envoyer votre requête, développez l'une des options suivantes :
Vous devriez recevoir une réponse JSON de ce type :
{ "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" }
Pour surveiller la progression de la tâche et afficher son résultat, accédez à la page Tâches Dataproc dans la console Google Cloud, puis cliquez sur Job ID
pour ouvrir la page Détails de la tâche.
Afficher les métadonnées d'une table dans BigQuery
Dans la console Google Cloud, accédez à la page BigQuery.
Afficher les métadonnées de table Iceberg
ICL Spark SQL
Les étapes suivantes vous montrent comment créer une table Iceberg avec des métadonnées de table stockées dans BigQuery Metastore à l'aide de la CLI Spark SQL exécutée sur le nœud maître d'un cluster Dataproc.
Utilisez SSH pour vous connecter au nœud maître de votre cluster Dataproc.
Dans le terminal de la session SSH, utilisez l'éditeur de texte
vi
ounano
pour copier les commandes suivantes dans un fichiericeberg-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;
Remplacez les éléments suivants :
- CATALOG_NAME: nom du catalogue Iceberg.
- BUCKET et WAREHOUSE_FOLDER: bucket et dossier Cloud Storage utilisés pour l'entrepôt Iceberg.
Dans le terminal de la session SSH, exécutez la commande
spark-sql
suivante pour créer le tableau de l'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
Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projet sont listés dans la section Project info (Informations sur le projet) du tableau de bord de la console Google Cloud.
- LOCATION: emplacement BigQuery compatible. L'emplacement par défaut est "États-Unis".
Afficher les métadonnées de table dans BigQuery
Dans la console Google Cloud, accédez à la page BigQuery.
Afficher les métadonnées de table Iceberg
Interface Web Zeppelin
Les étapes suivantes vous montrent comment créer une table Iceberg avec des métadonnées de table stockées dans BigQuery Metastore à l'aide de l'interface Web Zeppelin exécutée sur le nœud maître d'un cluster Dataproc .
Dans la console Google Cloud, accédez à la page Clusters Dataproc.
Sélectionnez le nom de votre cluster pour ouvrir la page Détails du cluster.
Cliquez sur l'onglet Web Interfaces (Interfaces Web) pour afficher la liste des liens de la passerelle des composants vers les interfaces Web des composants par défaut et facultatifs installés sur le cluster.
Cliquez sur le lien Zeppelin pour ouvrir l'interface Web Zeppelin.
Dans l'interface Web Zeppelin, cliquez sur le menu anonyme, puis sur Interprète pour ouvrir la page Interprètes.
Ajoutez deux fichiers JAR à l'interprète Spark Zeppelin, comme suit:
- Saisissez "Spark" dans le champ
Search interpreters
pour faire défiler la page jusqu'à la section de l'interprète Spark. - Cliquez sur edit (modifier).
Collez le code suivant dans le champ 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
Cliquez sur Enregistrer au bas de la section de l'interprète Spark, puis sur OK pour mettre à jour l'interprète et redémarrer l'interprète Spark avec les nouveaux paramètres.
- Saisissez "Spark" dans le champ
Dans le menu du notebook Zeppelin, cliquez sur Créer une note.
Dans la boîte de dialogue Create new note (Créer une note), saisissez un nom pour le notebook et acceptez l'interprète spark par défaut. Cliquez sur Créer pour ouvrir le notebook.
Copiez le code PySpark suivant dans votre notebook Zeppelin après avoir renseigné les variables.
%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()Remplacez les éléments suivants :
- PROJECT_ID : ID de votre projet Google Cloud . Les ID de projet sont listés dans la section Project info (Informations sur le projet) du tableau de bord de la console Google Cloud.
- CATALOG_NAME et NAMESPACE: le nom et l'espace de noms du catalogue Iceberg se combinent pour identifier la table Iceberg (
catalog.namespace.table_name
). - LOCATION: emplacement BigQuery compatible. L'emplacement par défaut est "États-Unis".
- BUCKET et WAREHOUSE_DIRECTORY: bucket et dossier Cloud Storage utilisés comme répertoire d'entrepôt Iceberg.
Cliquez sur l'icône d'exécution ou appuyez sur
Shift-Enter
pour exécuter le code. Une fois la tâche terminée, le message d'état indique "Spark Job Finished" (Tâche Spark terminée), et le résultat affiche le contenu de la table:Afficher les métadonnées de table dans BigQuery
Dans la console Google Cloud, accédez à la page BigQuery.
Afficher les métadonnées de table Iceberg