Utiliser BigLake Metastore avec le catalogue Iceberg REST

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Les fonctionnalités de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Remarque : Pour demander des commentaires ou de l'aide concernant cette fonctionnalité, envoyez un e-mail à l'adresse [e-mail].

Le catalogue REST Apache Iceberg géré dans le métastore BigLake assure l'interopérabilité entre tous vos moteurs de requête en offrant une source unique de vérité pour toutes vos données Iceberg. Il permet aux moteurs de requête, tels qu'Apache Spark, de découvrir, de lire les métadonnées et de gérer les tables Iceberg de manière cohérente.

Les tables Iceberg que vous utilisez avec le catalogue Iceberg REST sont appelées tables BigLake pour Apache Iceberg (preview). Il s'agit de tables Iceberg que vous créez à partir de moteurs Open Source et que vous stockez dans Cloud Storage. Ils peuvent être lus par des moteurs Open Source ou BigQuery. Les écritures ne sont acceptées que depuis les moteurs Open Source. Dans ce document, nous appelons ces tables "tables BigLake Iceberg".

Avant de commencer

1. Verify that billing is enabled for your Google Cloud project.

   Découvrez comment vérifier si la facturation est activée sur un projet.

2. Enable the BigLake API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

3. Facultatif : Demandez à un administrateur de configurer la distribution d'identifiants pour la première fois.
4. Facultatif : Découvrez comment fonctionne BigLake Metastore et pourquoi vous devriez l'utiliser.

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser le catalogue REST Iceberg dans le métastore BigLake, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Effectuez des tâches administratives, comme la gestion de l'accès des utilisateurs au catalogue, de l'accès au stockage et du mode d'authentification du catalogue :
  • Administrateur BigLake (roles/biglake.admin) sur le projet
  • Administrateur de l'espace de stockage (roles/storage.admin) sur le bucket Cloud Storage
• Lire les données de table en mode distribution d'identifiants : Lecteur BigLake (roles/biglake.viewer) sur le projet
• Écrire des données de table en mode distribution d'identifiants : Éditeur BigLake (roles/biglake.editor) sur le projet
• Lire les ressources de catalogue et les données de table en mode sans distribution d'identifiants :
  • Lecteur BigLake (roles/biglake.viewer) sur le projet
  • Lecteur des objets Storage (roles/storage.objectViewer) sur le bucket Cloud Storage
• Gérez les ressources du catalogue et écrivez des données de table en mode sans distribution d'identifiants :
  • Éditeur BigLake (roles/biglake.editor) sur le projet
  • Utilisateur d'objets Storage (roles/storage.objectUser) sur le bucket Cloud Storage.

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer le mode de distribution d'identifiants

Le mode de distribution des identifiants est un mécanisme de délégation d'accès au stockage qui permet aux administrateurs de métastore BigLake de contrôler les autorisations directement sur les ressources de métastore BigLake. Les utilisateurs du catalogue n'ont ainsi pas besoin d'avoir un accès direct aux buckets Cloud Storage. Il permet aux administrateurs BigLake d'accorder des autorisations aux utilisateurs sur des fichiers de données spécifiques.

Un administrateur de catalogue active la distribution d'identifiants sur le client de catalogue REST Iceberg.

En tant qu'utilisateur du catalogue, vous pouvez ensuite demander au catalogue Iceberg REST de renvoyer des identifiants de stockage à champ d'application limité en spécifiant la délégation d'accès, qui fait partie de la spécification de l'API Iceberg REST Catalog. Pour en savoir plus, consultez Configurer un moteur de requête avec le catalogue REST Iceberg.

Pour initialiser le catalogue et activer le mode de distribution d'identifiants, procédez comme suit.

1. Initialisez le catalogue à l'aide de la commande suivante :

   curl -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/v1/config?warehouse=gs://CLOUD_STORAGE_BUCKET_NAME

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet Google Cloud .
   • CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke la table Iceberg.

   La sortie de la commande curl ressemble à ceci : La valeur du préfixe de catalogue se trouve dans le champ overrides.prefix de la réponse :

   {
     "overrides": {
       "catalog_credential_mode": "CREDENTIAL_MODE_END_USER",
       "prefix": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME"
     },
     "endpoints": [
       "GET /v1/{prefix}/namespaces",
       "POST /v1/{prefix}/namespaces",
       "GET /v1/{prefix}/namespaces/{namespace}",
       "HEAD /v1/{prefix}/namespaces/{namespace}",
       "DELETE /v1/{prefix}/namespaces/{namespace}",
       "POST /v1/{prefix}/namespaces/{namespace}/properties",
       "GET /v1/{prefix}/namespaces/{namespace}/tables",
       "POST /v1/{prefix}/namespaces/{namespace}/tables",
       "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "POST /v1/{prefix}/namespaces/{namespace}/tables/{table}",
       "DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}"
     ]
   }
   

2. Activez le mode de distribution d'identifiants et extrayez le compte de service auquel accorder des autorisations à l'aide de la commande suivante :

   curl -X PATCH -H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" -H "Accept: application/json" -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" https://biglake.googleapis.com/iceberg/v1/restcatalog/extensions/PREFIX?update_mask=credential_mode -d '{"credential_mode":"CREDENTIAL_MODE_VENDED_CREDENTIALS"}'

   Remplacez PREFIX par le champ prefix du résultat de la commande précédente.

   Le résultat de la commande curl contient le compte de service, qui ressemble à ce qui suit :

   {
     "name": "projects/PROJECT_ID/catalogs/CLOUD_STORAGE_BUCKET_NAME",
     "credential_mode": "CREDENTIAL_MODE_VENDED_CREDENTIALS",
     "biglake-service-account": "BIGLAKE_SERVICE_ACCOUNT"
   }
   

3. Pour vous assurer que le compte de service BigLake que vous avez extrait à l'étape précédente dispose des autorisations nécessaires pour utiliser le mode de distribution d'identifiants, demandez à votre administrateur de lui attribuer le rôle Utilisateur d'objets Storage (roles/storage.objectUser) sur le bucket de stockage.

   Important : Vous devez accorder ce rôle au compte de service BigLake que vous avez extrait à l'étape précédente, et non à votre compte utilisateur. Si vous ne l'accordez pas au bon compte principal, vous risquez de rencontrer des erreurs d'autorisation.

Limites

Le catalogue REST Iceberg est soumis aux limites suivantes :

• Les buckets multirégionaux, les buckets birégionaux et les buckets avec un placement de région personnalisé ne sont pas acceptés.
• Lorsque vous utilisez le mode de distribution d'identifiants, vous devez définir la propriété io-impl sur org.apache.iceberg.gcp.gcs.GCSFileIO. La valeur par défaut, org.apache.iceberg.hadoop.HadoopFileIO, n'est pas acceptée.

Configurer le catalogue REST Iceberg

Cluster

Pour utiliser Spark avec le catalogue REST Iceberg sur Dataproc, commencez par créer un cluster avec le composant Iceberg :

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION

Remplacez les éléments suivants :

• CLUSTER_NAME : nom de votre cluster.
• PROJECT_ID : ID de votre projet Google Cloud .
• REGION : région du cluster Dataproc.
• DATAPROC_VERSION : version de l'image Dataproc, par exemple 2.2.

Après avoir créé le cluster, configurez votre session Spark pour qu'elle utilise le catalogue REST 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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue REST Iceberg.
• APP_NAME : nom de votre session Spark.
• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke les tables BigLake Iceberg.
• PROJECT_ID : projet facturé pour l'utilisation du catalogue REST Iceberg, qui peut être différent du projet propriétaire du bucket Cloud Storage. Pour en savoir plus sur la configuration du projet lorsque vous utilisez une API REST, consultez Paramètres système.

Cet exemple n'utilise pas la distribution d'identifiants. Pour utiliser la distribution d'identifiants, vous devez ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de catalogue REST Iceberg avec la valeur vended-credentials, en ajoutant la ligne suivante au générateur SparkSession :

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemple avec la distribution d'identifiants

L'exemple suivant configure le moteur de requête avec la distribution d'identifiants :

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Pour en savoir plus, consultez la section En-têtes dans RESTCatalog de la documentation Iceberg.

Les clusters Dataproc sont compatibles avec les flux d'autorisation Google pour Iceberg dans les versions suivantes :

• Versions 2.2.65 et ultérieures des images Dataproc sur Compute Engine 2.2.
• Versions d'image 2.3.11 et ultérieures de Dataproc sur Compute Engine 2.3.

Sans serveur

Envoyez une charge de travail par lot PySpark à Google Cloud Serverless pour Apache Spark avec la configuration suivante :

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/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

Remplacez les éléments suivants :

• PYSPARK_FILE : chemin d'accès gs:// Cloud Storage vers le fichier de votre application PySpark.
• PROJECT_ID : ID de votre projet Google Cloud .
• REGION : région de la charge de travail par lot Dataproc.
• RUNTIME_VERSION : version d'exécution Serverless pour Apache Spark (par exemple, 2.2).
• CATALOG_NAME : nom de votre catalogue REST Iceberg.
• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke les tables BigLake Iceberg.

Pour utiliser la distribution d'identifiants, vous devez ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de catalogue REST Iceberg avec la valeur vended-credentials, en ajoutant la ligne suivante aux configurations Serverless pour Apache Spark :

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemple avec la distribution d'identifiants

L'exemple suivant configure le moteur de requête avec la distribution d'identifiants :

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/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    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.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

Pour en savoir plus, consultez la section En-têtes dans RESTCatalog de la documentation Iceberg.

Serverless pour Apache Spark est compatible avec les flux d'autorisation Google pour Iceberg dans les versions d'exécution suivantes :

• Runtimes Serverless pour Apache Spark 2.2.60 et versions ultérieures
• Runtimes Serverless pour Apache Spark 2.3.10 et versions ultérieures

Trino

Pour utiliser Trino avec le catalogue REST Iceberg, créez un cluster Dataproc avec le composant Trino et configurez les propriétés du catalogue à l'aide de l'option gcloud dataproc clusters create --properties. L'exemple suivant crée un catalogue Trino nommé 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/v1/restcatalog,\
trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
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"

Remplacez les éléments suivants :

• CLUSTER_NAME : nom de votre cluster.
• REGION : région du cluster Dataproc.
• DATAPROC_VERSION : version de l'image Dataproc, par exemple 2.2.
• NETWORK_ID : ID du réseau du cluster. Pour en savoir plus, consultez Configuration du réseau du cluster Dataproc.
• CATALOG_NAME : nom de votre catalogue Trino utilisant le catalogue REST Iceberg.
• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke les tables BigLake Iceberg.
• PROJECT_ID : ID de votre projet Google Cloud à utiliser pour BigLake Metastore.

Une fois le cluster créé, utilisez SSH pour vous connecter à l'instance de VM principale, puis utilisez l'interface de ligne de commande Trino comme suit :

trino

Dataproc Trino est compatible avec les flux d'autorisation Google pour Iceberg dans les versions suivantes :

• Versions d'exécution Dataproc sur Compute Engine 2.2.65 et ultérieures
• Versions d'exécution Dataproc sur Compute Engine 2.3.11 et ultérieures
• Dataproc sur Compute Engine 3.0 n'est pas compatible.

Important : La distribution d'identifiants n'est pas compatible avec Dataproc Trino.

Iceberg 1.10 ou version ultérieure

Les versions Open Source d'Iceberg 1.10 et ultérieures sont compatibles avec les flux d'autorisation Google dans GoogleAuthManager. Voici un exemple de configuration d'Apache Spark pour utiliser le catalogue REST Iceberg du metastore BigLake.

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue REST Iceberg.
• APP_NAME : nom de votre session Spark.
• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke les tables BigLake Iceberg.
• PROJECT_ID : projet facturé pour l'utilisation du catalogue REST Iceberg, qui peut être différent du projet propriétaire du bucket Cloud Storage. Pour en savoir plus sur la configuration du projet lorsque vous utilisez une API REST, consultez Paramètres système.

L'exemple précédent n'utilise pas la distribution d'identifiants. Pour utiliser la distribution d'identifiants, vous devez ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de catalogue REST Iceberg avec la valeur vended-credentials, en ajoutant la ligne suivante au générateur SparkSession :

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemple avec la distribution d'identifiants

L'exemple suivant configure le moteur de requête avec la distribution d'identifiants :

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Pour en savoir plus, consultez la section En-têtes dans RESTCatalog de la documentation Iceberg.

Versions précédentes d'Iceberg

Pour les versions Open Source d'Iceberg antérieures à la version 1.10, vous pouvez configurer l'authentification OAuth standard en configurant une session avec les éléments suivants :

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue REST Iceberg.
• APP_NAME : nom de votre session Spark.
• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage qui stocke les tables BigLake Iceberg.
• PROJECT_ID : projet facturé pour l'utilisation du catalogue REST Iceberg, qui peut être différent du projet propriétaire du bucket Cloud Storage. Pour en savoir plus sur la configuration du projet lorsque vous utilisez une API REST, consultez Paramètres système.
• TOKEN : votre jeton d'authentification, qui est valide pendant une heure (par exemple, un jeton généré à l'aide de gcloud auth application-default print-access-token).

L'exemple précédent n'utilise pas la distribution d'identifiants. Pour utiliser la distribution d'identifiants, vous devez ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de catalogue REST Iceberg avec la valeur vended-credentials, en ajoutant la ligne suivante au générateur SparkSession :

.config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials')

Exemple avec la distribution d'identifiants

L'exemple suivant configure le moteur de requête avec la distribution d'identifiants :

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .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(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Pour en savoir plus, consultez la section En-têtes dans RESTCatalog de la documentation Iceberg.

Créer un espace de noms

Spark

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

spark.sql("USE NAMESPACE_NAME;")

Remplacez NAMESPACE_NAME par le nom de votre espace de noms.

Trino

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME;

USE CATALOG_NAME.SCHEMA_NAME;

Remplacez les éléments suivants :

• CATALOG_NAME : nom de votre catalogue Trino utilisant le catalogue REST Iceberg.
• SCHEMA_NAME : nom de votre schéma.

Créer une table

Spark

spark.sql("CREATE TABLE TABLE_NAME (id int, data string) USING ICEBERG;")

spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Remplacez les éléments suivants :

• NAMESPACE_NAME : nom de votre espace de noms
• TABLE_NAME : nom de votre table

Trino

CREATE TABLE TABLE_NAME (id int, data varchar);

DESCRIBE TABLE_NAME;

Remplacez TABLE_NAME par le nom de votre table.

Répertorier des tables

Spark

spark.sql("SHOW TABLES").show()

Trino

SHOW TABLES;

Insérer des données dans la table

L'exemple suivant insère des exemples de données dans la table :

Spark

spark.sql("INSERT INTO TABLE_NAME VALUES (1, \"first row\"), (2, \"second row\"), (3, \"third row\");")

Trino

INSERT INTO TABLE_NAME VALUES (1, 'first row'), (2, 'second row'), (3, 'third row');

Exécuter des requêtes sur une table

L'exemple suivant sélectionne toutes les données de la table :

Spark

spark.sql("SELECT * FROM TABLE_NAME;").show()

Trino

SELECT * FROM TABLE_NAME;

L'exemple suivant interroge la même table depuis BigQuery :

SELECT * FROM `CLOUD_STORAGE_BUCKET_NAME>NAMESPACE_OR_SCHEMA_NAME.TABLE_NAME`;

Remplacez les éléments suivants :

• CLOUD_STORAGE_BUCKET_NAME : nom du bucket Cloud Storage pour votre catalogue REST Iceberg. Par exemple, si votre URI est gs://iceberg_bucket, utilisez iceberg_bucket.

• NAMESPACE_OR_SCHEMA_NAME : espace de noms de la table si vous utilisez Spark ou nom du schéma de la table si vous utilisez Trino.

• TABLE_NAME : nom de votre table.

Modifier le schéma d'une table

L'exemple suivant ajoute une colonne à la table :

Spark

spark.sql("ALTER TABLE TABLE_NAME ADD COLUMNS ( desc string);")
spark.sql("DESCRIBE NAMESPACE_NAME.TABLE_NAME").show()

Remplacez les éléments suivants :

• NAMESPACE_NAME : nom de votre espace de noms
• TABLE_NAME : nom de votre table

Trino

ALTER TABLE TABLE_NAME ADD COLUMN desc varchar;
DESCRIBE SCHEMA_NAME.TABLE_NAME;

Remplacez les éléments suivants :

• SCHEMA_NAME : nom de votre schéma
• TABLE_NAME : nom de votre table

Supprimer une table

L'exemple suivant supprime la table de l'espace de noms indiqué :

Spark

spark.sql("DROP TABLE TABLE_NAME;")

Trino

DROP TABLE TABLE_NAME;

Tarifs

Pour en savoir plus sur les tarifs, consultez la page Tarifs de BigLake.

Étapes suivantes

• Découvrez comment gérer les ressources Iceberg avec BigLake Metastore.
• Découvrez les fonctionnalités supplémentaires de BigLake Metastore.