Configurer le catalogue REST Lakehouse Iceberg

Pour les nouveaux workflows, nous vous recommandons d'utiliser le point de terminaison du catalogue Apache Iceberg REST dans le catalogue d'exécution Lakehouse.

Ce point de terminaison sert de source unique de vérité, ce qui permet une interopérabilité fluide entre vos moteurs de requête. Il permet à des moteurs tels qu'Apache Spark de découvrir, lire et gérer de manière cohérente vos tables Google Cloud Lakehouse.

Cette approche est un bon choix si vous utilisez des moteurs Open Source pour accéder aux données dans Cloud Storage et que vous avez besoin d'une interopérabilité avec d'autres moteurs, y compris BigQuery. Il est compatible avec des fonctionnalités telles que la distribution d'identifiants pour un contrôle des accès précis et la réplication interrégionale et la reprise après sinistre.

En revanche, le point de terminaison Catalogue Apache Iceberg personnalisé pour BigQuery est une intégration antérieure. Bien que les workflows existants puissent continuer à l'utiliser, le catalogue REST offre une expérience plus standardisée et riche en fonctionnalités.

Avant de commencer

Avant de continuer, familiarisez-vous avec le catalogue d'environnements d'exécution Lakehouse et l'aperçu des points de terminaison du catalogue REST Iceberg.

  1. Vérifiez que la facturation est activée pour votre projet Google Cloud .

  2. Activez l'API BigLake.

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

    Activer l'API

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser le point de terminaison du catalogue Apache Iceberg REST dans le catalogue Lakehouse Runtime, demandez à votre administrateur de vous accorder les rôles IAM suivants :

  • Effectuer des tâches administratives, comme gérer l'accès des utilisateurs au catalogue et au stockage, ainsi que le mode de distribution des identifiants du catalogue :
  • Lire les données de table en mode distribution d'identifiants : Lecteur BigLake (roles/biglake.viewer) sur le projet. Si vous utilisez des moteurs de requête tels que Managed Service pour Apache Spark, Managed Service pour Apache Spark ou Dataflow pour lire les données des tables, accordez ce rôle au compte de service que vous utilisez pour exécuter des jobs dans ce moteur.
  • Écrire des données de table en mode distribution d'identifiants : Éditeur BigLake (roles/biglake.editor) sur le projet. Si vous utilisez des moteurs de requête tels que Managed Service pour Apache Spark, Managed Service pour Apache Spark ou Dataflow pour écrire des données de table, accordez ce rôle au compte de service que vous utilisez pour exécuter des jobs dans ce moteur.
  • Utilisez le compte de service du catalogue d'exécution Lakehouse provisionné automatiquement en mode de distribution d'identifiants : Utilisateur d'objets Storage (roles/storage.objectUser) sur le bucket Cloud Storage cible. Après avoir créé le catalogue, accordez explicitement le rôle Utilisateur d'objets de stockage (roles/storage.objectUser) sur votre bucket de stockage au compte de service du catalogue Lakehouse Runtime provisionné automatiquement.
  • Lire les ressources de catalogue et les données de table en mode sans distribution d'identifiants :
  • Gérer les ressources du catalogue et écrire des données de table en mode sans distribution d'identifiants :
  • Effectuez des opérations de langage de manipulation de données (LMD) avec la fédération de catalogues BigQuery :
    • Éditeur de données BigQuery (roles/bigquery.dataEditor) sur le projet
    • Administrateur de l'espace de stockage (roles/storage.admin) sur le bucket Cloud Storage. Si vous utilisez des moteurs de requête tels que Managed Service pour Apache Spark pour effectuer des opérations LMD, accordez ces rôles au compte de service que vous utilisez pour exécuter des jobs dans ce moteur.

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 via des rôles personnalisés ou d'autres rôles prédéfinis.

Limites

Le point de terminaison du catalogue Apache Iceberg REST est soumis aux limites suivantes :

Limites générales

  • Trino n'est compatible avec la fédération de catalogues BigQuery que lorsque vous utilisez les versions d'image 2.3.16 et ultérieures de Managed Service pour Apache Spark sur Compute Engine.
  • 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.

Limites des tableaux

  • Les tables gérées via le point de terminaison du catalogue Apache Iceberg REST ne sont pas compatibles avec le contrôle précis des accès (FGAC), comme la sécurité au niveau des lignes et des colonnes.

Limites de données

  • Seuls les fichiers Parquet sont acceptés. Pour en savoir plus sur la façon dont BigQuery gère les fichiers Parquet, consultez Charger des données Parquet depuis Cloud Storage.
  • La taille du fichier Iceberg metadata.json est limitée à 1 Mo. Pour demander une augmentation de cette limite, contactez l'équipe chargée de votre compte Google.

Limites des requêtes

  • Il est impossible de créer des vues sur des tables Apache Iceberg gérées par le point de terminaison du catalogue Apache Iceberg REST dans BigQuery.
  • Les tables de métadonnées Apache Iceberg (telles que .snapshots ou .files) ne peuvent pas être interrogées dans BigQuery à l'aide d'identifiants de nom en cinq parties. Vous pouvez interroger ces tables à l'aide de Spark.

Configurer le point de terminaison du catalogue REST Iceberg

Avant de configurer votre catalogue, nous vous recommandons de lire la présentation des points de terminaison du catalogue REST Apache Iceberg pour comprendre sa hiérarchie de ressources, ses types de catalogues et sa structure de dénomination.

Voici les étapes générales à suivre lorsque vous utilisez le point de terminaison du catalogue Apache Iceberg REST dans le catalogue d'exécution Lakehouse :

  1. En fonction de la présentation du point de terminaison du catalogue REST Iceberg, choisissez l'emplacement de l'entrepôt de catalogue (Cloud Storage ou BigQuery).
  2. Si vous utilisez un entrepôt gs:// Cloud Storage, créez un catalogue qui pointe vers l'emplacement de votre entrepôt.
  3. Configurez votre application cliente pour qu'elle utilise le point de terminaison du catalogue Apache Iceberg REST.
  4. Créez un espace de noms ou un schéma pour organiser vos tables.
  5. Créez et interrogez des tables à l'aide de votre client configuré.

Créer un catalogue

Vous pouvez créer un catalogue qui utilise les identifiants de l'utilisateur final ou le mode de distribution des identifiants.

  • Avec les identifiants de l'utilisateur final, le catalogue transmet l'identité de l'utilisateur final qui y accède à Cloud Storage pour les vérifications d'autorisation.

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

Remarques

Familiarisez-vous avec les exigences en matière d'emplacement avant de créer un catalogue.

  • Lorsque vous créez un espace de noms, il utilise automatiquement la même région que votre catalogue.

  • Si votre catalogue utilise un bucket multirégional et que vous souhaitez l'utiliser avec les régions multiples BigQuery (US ou EU), vous devez supprimer le catalogue et le recréer pour spécifier l'emplacement principal.

Identifiants de l'utilisateur final

Console

  1. Ouvrez la page Lakehouse dans la console Google Cloud .

    Accéder à Lakehouse

  2. Cliquez sur Créer un catalogue.

  3. Dans le champ Sélectionner un bucket Cloud Storage, saisissez le nom du bucket Cloud Storage à utiliser avec votre catalogue. Vous pouvez également cliquer sur Parcourir pour choisir un bucket existant ou en créer un. Vous ne pouvez avoir qu'un seul catalogue par bucket Cloud Storage.

  4. Dans le champ Authentication method (Méthode d'authentification), sélectionnez End-user credentials (Identifiants de l'utilisateur final).

  5. Cliquez sur Créer.

gcloud

Exécutez la commande gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user \
    [--primary-location LOCATION]

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue. Pour les tables Apache Iceberg compatibles avec le catalogue du runtime Lakehouse, ce nom correspond souvent à l'ID du bucket Cloud Storage utilisé avec le catalogue REST. Par exemple, si votre bucket est gs://bucket-id, le nom du catalogue peut être bucket-id. Ce nom est également utilisé comme identifiant de catalogue lorsque vous interrogez ces tables depuis BigQuery.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • LOCATION : (facultatif) région principale du catalogue pour assurer l'interopérabilité avec BigQuery. Pour les buckets Cloud Storage situés dans la région des États-Unis (par exemple, US ou us-central1) ou dans la région de l'UE (par exemple, EU ou europe-west4), spécifiez US ou EU, respectivement, pour vous assurer que le catalogue est accessible et disponible pour les requêtes depuis les régions multirégionales BigQuery correspondantes. Pour en savoir plus, consultez Régions des buckets et des catalogues.

Mode de distribution d'identifiants

Un administrateur de catalogue active la distribution d'identifiants lorsqu'il crée ou met à jour un catalogue. En tant qu'utilisateur du catalogue, vous pouvez ensuite demander au point de terminaison du catalogue Apache Iceberg REST de renvoyer des identifiants de stockage à accès limité en spécifiant la délégation d'accès lorsque vous configurez le point de terminaison du catalogue Apache Iceberg REST.

Le compte de service du catalogue d'exécution Lakehouse provisionné automatiquement nécessite le rôle explicite d'utilisateur d'objets de stockage (roles/storage.objectUser) sur le bucket Cloud Storage cible. Par défaut, il est créé avec un accès en lecture seule. Sans ce rôle, les identifiants vendus n'auront pas une portée suffisante pour effectuer des écritures de stockage. Si vous utilisez des outils tels que gcloud ou Terraform, vous devez attribuer ce rôle manuellement.

Console

  1. Dans la console Google Cloud , ouvrez la page Lakehouse.

    Accéder à Lakehouse

  2. Cliquez sur Créer un catalogue. La page Créer un catalogue s'ouvre.

  3. Pour Sélectionner un bucket Cloud Storage, saisissez le nom du bucket Cloud Storage à utiliser avec votre catalogue. Vous pouvez également cliquer sur Parcourir pour choisir un bucket existant dans une liste ou en créer un. Vous ne pouvez avoir qu'un seul catalogue par bucket Cloud Storage.

  4. Dans le champ Authentication method (Méthode d'authentification), sélectionnez Credential vending mode (Mode de distribution d'identifiants).

  5. Cliquez sur Créer.

    Votre catalogue est créé et la page Détails du catalogue s'ouvre.

  6. Sous Méthode d'authentification, cliquez sur Définir les autorisations du bucket.

  7. Dans la boîte de dialogue, cliquez sur Confirmer.

    Cela permet de vérifier que le compte de service de votre catalogue dispose du rôle Administrateur des objets de l'espace de stockage sur votre bucket de stockage.

gcloud

Exécutez la commande gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue. Ce nom correspond souvent à l'ID de bucket Cloud Storage utilisé avec le catalogue REST. Par exemple, si votre bucket est gs://bucket-id, le nom du catalogue peut être bucket-id. Ce nom est également utilisé comme identifiant de catalogue lorsque vous interrogez ces tables depuis BigQuery.
  • PROJECT_ID : ID de votre projet Google Cloud .

  • LOCATION : (facultatif) région principale du catalogue pour assurer l'interopérabilité avec BigQuery. Pour les buckets Cloud Storage situés dans la région des États-Unis (par exemple, US ou us-central1) ou dans la région de l'UE (par exemple, EU ou europe-west4), spécifiez US ou EU, respectivement, pour vous assurer que le catalogue est accessible et disponible pour les requêtes depuis les régions multirégionales BigQuery correspondantes. Pour en savoir plus, consultez Régions des buckets et des catalogues.

    Après avoir créé le catalogue, accordez explicitement le rôle Utilisateur d'objets de stockage (roles/storage.objectUser) sur votre bucket de stockage au compte de service du catalogue Lakehouse Runtime provisionné automatiquement.

Configurer l'application cliente

Après avoir créé un catalogue, configurez votre application cliente pour l'utiliser. Ces exemples vous montrent comment configurer l'authentification avec ou sans distribution d'identifiants.

Cluster

Pour utiliser Spark avec le point de terminaison du catalogue Apache Iceberg REST sur Managed Service pour Apache Spark, vous pouvez utiliser des propriétés pour simplifier la configuration ou configurer la session manuellement.

Créez un cluster avec la propriété de catalogue :

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --project=PROJECT_ID \
    --region=REGION \
    --optional-components=ICEBERG \
    --image-version=DATAPROC_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Remplacez les éléments suivants :

  • CLUSTER_NAME : nom de votre cluster.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • REGION : région du cluster Managed Service pour Apache Spark.
  • DATAPROC_VERSION : version de l'image Managed Service pour Apache Spark (par exemple, 2.2).
  • CATALOG_NAME : nom du catalogue Lakehouse à utiliser dans Spark. Elle peut être identique à CATALOG_ID.
  • CATALOG_ID : ID du catalogue Lakehouse que vous avez créé.

Créez ensuite une session Spark sans spécifier de paramètres de catalogue manuel :

from pyspark.sql import SparkSession

spark = SparkSession.builder.appName("APP_NAME").getOrCreate()

Configuration manuelle

Si vous n'utilisez pas la propriété du cluster, créez un cluster comme décrit ci-dessus (sans l'option --properties), puis configurez manuellement votre session Spark :

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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom du point de terminaison de votre catalogue REST Apache Iceberg.
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API. Définissez la valeur sur v1beta si vous devez contourner un problème connu lié à la génération de l'origine des données.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Utilisez gs://CLOUD_STORAGE_BUCKET_NAME. Pour utiliser la fédération de catalogues BigQuery, consultez Utiliser la fédération de catalogues avec BigQuery.
  • PROJECT_ID : projet facturé pour l'utilisation du point de terminaison du catalogue Apache Iceberg REST, 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.

Configurer avec la distribution d'identifiants

Pour utiliser la distribution d'identifiants, vous devez utiliser un catalogue en mode de distribution d'identifiants et 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/REST_API_VERSION/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('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 Apache Iceberg.

Les clusters Managed Service pour Apache Spark sont compatibles avec les flux d'autorisation Google pour Apache Iceberg dans les versions suivantes :

  • Versions 2.2.65 et ultérieures des images Managed Service pour Apache Spark sur Compute Engine 2.2.
  • Versions 2.3.11 et ultérieures des images Managed Service pour Apache Spark sur Compute Engine 2.3.

Sans serveur

Envoyez une charge de travail par lot PySpark à Managed Service pour Apache Spark à l'aide de propriétés pour simplifier la configuration (recommandé) ou en spécifiant tous les paramètres.

Envoyez un job par lot avec la propriété de catalogue :

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="dataproc:dataproc.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Configuration manuelle

Si vous préférez spécifier manuellement toutes les propriétés, utilisez 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/REST_API_VERSION/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=WAREHOUSE_PATH,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    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"

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 Managed Service pour Apache Spark.
  • RUNTIME_VERSION : version d'exécution de Managed Service pour Apache Spark (par exemple, 2.2).
  • CATALOG_NAME : nom du point de terminaison de votre catalogue REST Apache Iceberg.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API. Définissez la valeur sur v1beta si vous devez contourner un problème connu lié à la génération de l'origine des données.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Utilisez gs://CLOUD_STORAGE_BUCKET_NAME. Pour utiliser la fédération de catalogues BigQuery, consultez Utiliser la fédération de catalogues avec BigQuery.

Configurer avec la distribution d'identifiants

Pour utiliser la distribution d'identifiants, vous devez utiliser un catalogue en mode de distribution d'identifiants et ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de point de terminaison du catalogue Apache Iceberg REST avec la valeur vended-credentials en ajoutant la ligne suivante aux configurations Managed Service 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/REST_API_VERSION/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.gcs.oauth2.refresh-credentials-endpoint=https://oauth2.googleapis.com/token, \
    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 Apache Iceberg.

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

  • Versions d'exécution Managed Service pour Apache Spark 2.2.60 et ultérieures
  • Versions 2.3.10 et ultérieures des environnements d'exécution Managed Service pour Apache Spark 2.3

Trino

Pour utiliser Trino avec le point de terminaison du catalogue Apache Iceberg REST, créez un cluster Managed Service pour Apache Spark avec le composant Trino et configurez les propriétés du catalogue à l'aide de l'indicateur 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/REST_API_VERSION/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=WAREHOUSE_PATH,\
    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 Managed Service pour Apache Spark.
  • DATAPROC_VERSION : version de l'image Managed Service pour Apache Spark (par exemple, 2.2).
  • NETWORK_ID : ID du réseau du cluster. Pour en savoir plus, consultez Configuration du réseau de cluster Managed Service pour Apache Spark.
  • CATALOG_NAME : nom de votre catalogue Trino utilisant le point de terminaison du catalogue Apache Iceberg REST.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API. Définissez la valeur sur v1beta si vous devez contourner un problème connu lié à la génération de l'origine des données.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Utilisez gs://CLOUD_STORAGE_BUCKET_NAME.
  • PROJECT_ID : ID de votre projet Google Cloud à utiliser pour le catalogue du runtime Lakehouse.

Une fois le cluster créé, connectez-vous à l'instance de VM principale et utilisez la CLI Trino :

trino --catalog=CATALOG_NAME

Managed Service pour Apache Spark Trino est compatible avec les flux d'autorisation Google pour Apache Iceberg dans les versions suivantes :

  • Versions d'exécution 2.2 de Managed Service pour Apache Spark sur Compute Engine 2.2.65 et versions ultérieures
  • Versions d'exécution 2.3.11 et ultérieures de Managed Service pour Apache Spark sur Compute Engine 2.3
  • Managed Service pour Apache Spark sur Compute Engine 3.0 n'est pas compatible.

Configurer avec la distribution d'identifiants

La distribution d'identifiants n'est compatible qu'avec Trino version 481 ou ultérieure.

Apache Iceberg 1.10 ou version ultérieure

Les versions Open Source d'Apache Iceberg 1.10 et ultérieures sont compatibles avec les flux d'autorisation Google dans GoogleAuthManager. Voici un exemple de configuration de Spark pour utiliser le point de terminaison du catalogue du runtime Lakehouse et du catalogue REST Apache 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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom du point de terminaison de votre catalogue REST Apache Iceberg.
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API. Définissez la valeur sur v1beta si vous devez contourner un problème connu lié à la génération de l'origine des données.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Utilisez gs://CLOUD_STORAGE_BUCKET_NAME. Pour utiliser la fédération de catalogues BigQuery, consultez Utiliser la fédération de catalogues avec BigQuery.
  • PROJECT_ID : projet facturé pour l'utilisation du point de terminaison du catalogue Apache Iceberg REST, 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.

Configurer avec la distribution d'identifiants

L'exemple précédent n'utilise pas la distribution d'identifiants. Pour utiliser la distribution d'identifiants, vous devez utiliser un catalogue en mode de distribution d'identifiants et ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de point de terminaison du catalogue Apache Iceberg REST 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/REST_API_VERSION/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('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 Apache Iceberg.

Versions précédentes d'Apache Iceberg

Pour les versions open source d'Apache 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/REST_API_VERSION/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'WAREHOUSE_PATH') \
  .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('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom du point de terminaison de votre catalogue REST Apache Iceberg.
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API. Définissez la valeur sur v1beta si vous devez contourner un problème connu lié à la génération de l'origine des données.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Utilisez gs://CLOUD_STORAGE_BUCKET_NAME. Pour utiliser la fédération de catalogues BigQuery, consultez Utiliser la fédération de catalogues avec BigQuery.
  • PROJECT_ID : projet facturé pour l'utilisation du point de terminaison du catalogue Apache Iceberg REST, 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).

Configurer avec la distribution d'identifiants

L'exemple précédent n'utilise pas la distribution d'identifiants. Pour utiliser la distribution d'identifiants, vous devez utiliser un catalogue en mode de distribution d'identifiants et ajouter l'en-tête X-Iceberg-Access-Delegation aux requêtes de point de terminaison du catalogue Apache Iceberg REST 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/REST_API_VERSION/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('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 Apache Iceberg.

Créer un espace de noms ou un schéma

Une fois votre client configuré, créez un espace de noms ou un schéma pour organiser vos tables. La syntaxe permettant de créer un espace de noms ou un schéma varie en fonction de votre moteur de requête. Les exemples suivants montrent comment les créer à l'aide de Spark et Trino.

Spark

Entrepôt Cloud Storage

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

Entrepôt Cloud Storage

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 point de terminaison du catalogue Apache Iceberg REST.
  • SCHEMA_NAME : nom de votre schéma.

Étapes suivantes