Configurer le point de terminaison du catalogue REST Iceberg Lakehouse

Pour les nouveaux catalogues, nous vous recommandons d'utiliser le point de terminaison du catalogue REST Apache Iceberg dans le catalogue d'environnements d'exécution Lakehouse. Ce point de terminaison fournit une interface standardisée entièrement gérée basée sur l'API Apache Iceberg REST Catalog Open Source.

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 vos tables Google Cloud Lakehouse.

Cette approche est idéale si vous utilisez des moteurs OSS ou tiers compatibles 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 plus riche en fonctionnalités.

Avant de commencer

Avant de continuer, familiarisez-vous avec le catalogue d'environnements d'exécution Lakehouse et la présentation des points de terminaison du catalogue REST Iceberg.

Si vous possédez des tables Apache Iceberg de version 1 (V1), vous devez les mettre à niveau avant de les utiliser avec le point de terminaison du catalogue Apache Iceberg REST. Pour en savoir plus, consultez Mettre à niveau les tables Iceberg V1 vers V2.

  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 :

  • Effectuez des tâches administratives, comme la gestion de l'accès des utilisateurs au catalogue et au stockage, ainsi que le mode de distribution des identifiants du catalogue :
  • Enregistrez des tables dans un catalogue BigLake : Administrateur BigLake (roles/biglake.admin) sur le projet.
  • 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 de 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 tous les buckets Cloud Storage associés. Après avoir créé le catalogue, accordez explicitement le rôle Utilisateur d'objets Storage (roles/storage.objectUser) sur tous les buckets de stockage associés au compte de service du catalogue d'exécution Lakehouse 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 :

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

  • Les tables Apache Iceberg V2 (disponibilité générale) et V3 (preview) sont compatibles. Les tables Iceberg V1 ne sont pas acceptées. Avant d'utiliser des tables V1 existantes avec le point de terminaison du catalogue REST Apache Iceberg, vous devez les mettre à niveau vers une version compatible.
  • Trino n'est compatible avec la fédération de catalogues BigQuery que lorsque vous utilisez Managed Service pour Apache Spark sur les versions 2.3.16 et ultérieures des images Compute Engine 2.3.
  • Lorsque vous utilisez le mode de distribution d'identifiants, si le moteur de requête vous permet de définir la propriété io-impl pour une connexion au catalogue, vous devez la définir sur org.apache.iceberg.gcp.gcs.GCSFileIO.
  • Les buckets avec espace de noms hiérarchique ne sont actuellement pas compatibles avec le mode de distribution d'identifiants.

Limites des tableaux

  • Vous ne pouvez pas créer ni modifier de tables dans le point de terminaison du catalogue REST Apache Iceberg à l'aide d'instructions LDD (langage de définition de données) ou LMD (langage de manipulation de données) BigQuery. Vous pouvez modifier ces tables à l'aide de l'API BigQuery (avec l'outil de ligne de commande bq ou les bibliothèques clientes), mais vous risquez d'apporter des modifications incompatibles avec le moteur externe.
  • 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.
  • Il est interdit de définir les propriétés de la table Iceberg write.data.path ou write.metadata.path sur des valeurs autres que celles par défaut.
  • Les chemins d'accès aux tables doivent être imbriqués dans le chemin d'accès de l'espace de noms parent (par exemple, gs://{namespace_path}/.../{table_name}). Pour éviter les conflits et améliorer la sécurité, un suffixe de chaîne aléatoire est automatiquement ajouté à l'emplacement obtenu (par exemple, gs://{namespace_path}/{table_name}/{random_suffix}).

Limitations liées aux 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

  • 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 REST Apache Iceberg dans le catalogue d'exécution Lakehouse :

  1. En fonction de la présentation des points de terminaison du catalogue REST Iceberg, choisissez votre type de catalogue. Vous pouvez configurer un catalogue multibucket (bl://) (recommandé) ou un catalogue monobucket (gs://).
  2. 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é.

Remarques

Considérez les options suivantes pour le mode d'authentification et la configuration du stockage.

Mode d'identifiants (champ d'application)

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

  • 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.

  • Mode de distribution des identifiants : mécanisme de délégation d'accès au stockage qui permet aux administrateurs du catalogue du runtime Lakehouse de contrôler les autorisations directement sur les ressources du catalogue du runtime Lakehouse, ce qui évite aux utilisateurs du catalogue 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.

Type de bucket

Vous pouvez choisir de créer un catalogue à un seul bucket ou à plusieurs buckets.

  • Multi-bucket (bl://) (recommandé) : cette configuration permet à votre catalogue d'associer plusieurs buckets et de nommer votre catalogue indépendamment de tout nom de bucket. Les catalogues multibuckets ne sont pas compatibles avec la console Google Cloud .
  • Bucket unique (gs://) : cette configuration limite votre catalogue à un seul bucket et verrouille le nom du catalogue sur le nom du bucket. Il est déconseillé pour les nouveaux projets.

Emplacement

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 multirégions BigQuery (US ou EU), vous devez supprimer le catalogue et le recréer pour spécifier l'emplacement principal.

Créer un catalogue

Suivez ces étapes pour créer un catalogue en fonction du mode d'authentification et du type de bucket de votre choix.

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. Pour Type de catalogue, sélectionnez Bucket Cloud Storage.

  4. Saisissez ou recherchez le bucket Cloud Storage à utiliser avec votre catalogue (pour un catalogue à bucket unique (gs://), vous ne pouvez avoir qu'un seul catalogue par bucket, et le nom du catalogue correspond au nom du bucket).

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

  6. Cliquez sur Créer.

gcloud

Créer un catalogue multibuckets (bl://) (recommandé)

Cette configuration permet à votre catalogue d'associer plusieurs buckets et de nommer votre catalogue indépendamment de tout nom de bucket.

Pour créer un catalogue multibuckets (bl://) (recommandé), exécutez la commande gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode end-user \
    [--primary-location LOCATION]

Créer un catalogue à bucket unique (gs://)

Pour créer un catalogue à un seul bucket (gs://), exécutez la commande suivante :

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode end-user

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue. Pour les catalogues multibuckets (bl://) (recommandés), il s'agit du nom de votre catalogue personnalisé. Pour les catalogues à bucket unique (gs://), cela correspond à l'ID de bucket Cloud Storage utilisé avec le catalogue REST. Ce nom est également utilisé comme identifiant de catalogue lorsque vous interrogez ces tables depuis BigQuery.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • DEFAULT_LOCATION : spécifiez l'emplacement de stockage par défaut du catalogue. Vous pouvez spécifier un bucket (gs://my-bucket) ou un sous-chemin (gs://my-bucket/path). Tous les espaces de noms et toutes les tables du catalogue doivent se trouver sous le chemin spécifié. Par exemple, si vous spécifiez gs://my-bucket/path, vous ne pouvez pas créer d'espaces de noms ni de tables sous gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS : (facultatif) liste d'emplacements de stockage supplémentaires autorisés, séparés par une virgule, au format gs://my-bucket-1/...,gs://my-bucket-2/.... Si vous spécifiez un chemin d'accès (tel que gs://my-bucket/path), tous les espaces de noms ou tables de ce bucket doivent se trouver sous ce chemin d'accès. Tous les emplacements de stockage cloud configurés (emplacement par défaut et emplacements soumis à restriction) doivent se trouver dans le même groupe de régions ou la même juridiction géographique (par exemple, les États-Unis, l'Europe, le Canada ou l'Asie). Par exemple, vous ne pouvez pas mélanger un bucket aux États-Unis avec un bucket en Europe. Pour obtenir la liste des emplacements compatibles, consultez Emplacements Lakehouse. Avertissement de sécurité : Évitez de configurer des chemins qui se chevauchent avec d'autres catalogues pour éviter l'exposition non autorisée des identifiants. Pour en savoir plus, consultez Stockage dans plusieurs buckets.
  • 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 Utilisateur d'objets Storage (roles/storage.objectUser) sur tous les buckets Cloud Storage associés. Par défaut, il n'a aucun accès. Sans ce rôle, les identifiants fournis n'auront pas une portée suffisante pour effectuer des opérations d'écriture 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 Type de catalogue, sélectionnez Bucket Cloud Storage.

  4. Saisissez ou recherchez le bucket Cloud Storage à utiliser avec votre catalogue (pour un catalogue à bucket unique (gs://), vous ne pouvez avoir qu'un seul catalogue par bucket, et le nom du catalogue correspond au nom du bucket).

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

  6. Cliquez sur Créer.

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

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

  8. 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 Utilisateur d'objets de stockage sur tous les buckets de stockage associés.

gcloud

Créer un catalogue multibuckets (bl://) (recommandé)

Cette configuration permet à votre catalogue d'associer plusieurs buckets et de nommer votre catalogue indépendamment de tout nom de bucket.

Pour créer un catalogue multibuckets (bl://) (recommandé), exécutez la commande gcloud biglake iceberg catalogs create.

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type biglake \
    --default-location DEFAULT_LOCATION \
    [--restricted-locations RESTRICTED_LOCATIONS] \
    --credential-mode vended-credentials \
    [--primary-location LOCATION]

Créer un catalogue à bucket unique (gs://)

Pour créer un catalogue à un seul bucket (gs://), exécutez la commande suivante :

gcloud biglake iceberg catalogs create \
    CATALOG_NAME \
    --project PROJECT_ID \
    --catalog-type gcs-bucket \
    --credential-mode vended-credentials

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue. Pour les catalogues multibuckets (bl://) (recommandé), il s'agit du nom de votre catalogue personnalisé. Pour les catalogues à bucket unique (gs://), cela correspond à l'ID de bucket Cloud Storage utilisé avec le catalogue REST. Ce nom est également utilisé comme identifiant de catalogue lorsque vous interrogez ces tables depuis BigQuery.
  • PROJECT_ID : ID de votre projet Google Cloud .
  • DEFAULT_LOCATION : spécifiez l'emplacement de stockage par défaut du catalogue. Vous pouvez spécifier un bucket (gs://my-bucket) ou un sous-chemin (gs://my-bucket/path). Tous les espaces de noms et toutes les tables du catalogue doivent se trouver sous le chemin spécifié. Par exemple, si vous spécifiez gs://my-bucket/path, vous ne pouvez pas créer d'espaces de noms ni de tables sous gs://my-bucket/another/path.
  • RESTRICTED_LOCATIONS : (facultatif) liste d'emplacements de stockage supplémentaires autorisés, séparés par une virgule, au format gs://my-bucket-1/...,gs://my-bucket-2/.... Si vous spécifiez un chemin d'accès (tel que gs://my-bucket/path), tous les espaces de noms ou tables de ce bucket doivent se trouver sous ce chemin d'accès. Tous les emplacements de stockage cloud configurés (emplacement par défaut et emplacements soumis à restriction) doivent se trouver dans le même groupe de régions ou la même juridiction géographique (par exemple, les États-Unis, l'Europe, le Canada ou l'Asie). Par exemple, vous ne pouvez pas mélanger un bucket aux États-Unis avec un bucket en Europe. Pour obtenir la liste des emplacements compatibles, consultez Emplacements Lakehouse. Avertissement de sécurité : Évitez de configurer des chemins qui se chevauchent avec d'autres catalogues pour éviter l'exposition non autorisée des identifiants. Pour en savoir plus, consultez Stockage dans plusieurs buckets.

  • 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, attribuez explicitement le rôle Utilisateur des objets Storage (roles/storage.objectUser) sur tous les buckets Storage associés au compte de service du catalogue d'exécution Lakehouse 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

Créez un cluster Managed Service pour Apache Spark sur Compute Engine à l'aide de propriétés de configuration simplifiées (recommandé) ou en spécifiant les propriétés 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.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.3).
  • CATALOG_NAME : nom du catalogue Spark local (par exemple, my_catalog). Il peut être identique à CATALOG_ID.
  • CATALOG_ID : ID du catalogue que vous avez créé.

Dans le fichier d'application PySpark, créez SparkSession sans spécifier de configurations de catalogue :

from pyspark.sql import SparkSession

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

Configuration manuelle

Si vous n'utilisez pas la propriété de configuration simplifiée, créez un cluster comme décrit ci-dessus, mais sans l'indicateur --properties. Configurez ensuite votre SparkSession manuellement :

import pyspark
from pyspark.context import SparkContext
from pyspark.sql import SparkSession

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.sql.defaultCatalog', 'CATALOG_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') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom du catalogue Spark local (par exemple, my_catalog).
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Pour les catalogues BigLake, utilisez bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Pour les catalogues de bucket Cloud Storage, 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 REST Apache 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.

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('spark.sql.defaultCatalog', 'CATALOG_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(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .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 de configuration simplifiées (recommandé) ou en spécifiant les propriétés manuellement.

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.lakehouse.catalog.CATALOG_NAME=projects/PROJECT_ID/catalogs/CATALOG_ID"

Remplacez les éléments suivants :

  • PYSPARK_FILE : chemin d'accès gs:// Cloud Storage à votre fichier d'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.3).
  • CATALOG_NAME : nom du catalogue Spark local (par exemple, my_catalog). Il peut être identique à CATALOG_ID.
  • CATALOG_ID : ID du catalogue que vous avez créé.

Dans le fichier d'application PySpark, créez SparkSession sans spécifier de configurations de catalogue :

from pyspark.sql import SparkSession

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

Configuration manuelle

Si vous n'utilisez pas la propriété de configuration simplifiée, vous devez spécifier manuellement les configurations de catalogue :

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.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions"

Remplacez les éléments suivants :

  • PYSPARK_FILE : chemin d'accès gs:// Cloud Storage à votre fichier d'application PySpark.
  • 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.3).
  • CATALOG_NAME : nom du catalogue Spark local (par exemple, my_catalog).
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Pour les catalogues BigLake, utilisez bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Pour les catalogues de bucket Cloud Storage, 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 REST Apache 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.

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=WAREHOUSE_PATH,\
    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.catalog.CATALOG_NAME.io-impl=org.apache.iceberg.gcp.gcs.GCSFileIO,\
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials,\"
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions

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 :

  • Runtimes Managed Service pour Apache Spark 2.2 version 2.2.60 et ultérieures
  • Runtimes Managed Service pour Apache Spark 2.3.10 et versions ultérieures

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 REST Apache Iceberg.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Pour les catalogues BigLake, utilisez bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Pour les catalogues de bucket Cloud Storage, 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 et 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 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 catalogue Spark local (par exemple, my_catalog).
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Pour les catalogues BigLake, utilisez bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Pour les catalogues de bucket Cloud Storage, 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 REST Apache 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.

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', '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(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 catalogue Spark local (par exemple, my_catalog).
  • APP_NAME : nom de votre session Spark.
  • REST_API_VERSION : définissez cette option sur v1 pour la version stable de l'API.
  • WAREHOUSE_PATH : chemin d'accès à votre entrepôt. Pour les catalogues BigLake, utilisez bl://projects/PROJECT_ID/catalogs/CATALOG_ID. Pour les catalogues de bucket Cloud Storage, 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 REST Apache 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).

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', '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(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

Après avoir configuré votre client, 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.

Console

  1. Dans la console Google Cloud , accédez à Lakehouse.

    Accéder à Lakehouse

  2. Sélectionnez un catalogue existant ou créez-en un si vous n'en avez pas.

  3. Dans la barre de menus, cliquez sur + Créer un espace de noms.

  4. Dans le champ Nom de l'espace de noms, saisissez un nom unique pour votre espace de noms.

  5. Dans le champ Emplacement, spécifiez le chemin d'accès à associer à votre espace de noms :

    • Multi-bucket (bl://) (recommandé) : vous pouvez définir n'importe quel lieu personnalisé, à condition qu'il se trouve dans un lieu autorisé par le catalogue (default_location ou restricted_locations). Si vous ne spécifiez pas de lieu, l'espace de noms est créé dans le lieu par défaut du catalogue (par exemple, gs://{path-to-default-location}/{namespace_name}). Notez que les catalogues multi-bucket (bl://) (recommandés) ne peuvent pas être gérés dans la console.
    • Bucket unique (gs://) : l'emplacement de l'espace de noms est automatiquement hérité du bucket unique du catalogue.

  6. Cliquez sur Créer.

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

Mettre à niveau un catalogue

Si vous disposez d'un catalogue à un seul bucket (gs://), vous pouvez le mettre à niveau vers un catalogue à plusieurs buckets (bl://), ce qui est recommandé. La mise à niveau vous permet d'associer plusieurs buckets et de configurer des zones géographiques restreintes tout en conservant le nom de catalogue d'origine.

Pour mettre à niveau votre catalogue, consultez Mettre à jour un catalogue.

Étapes suivantes