Utiliser le catalogue Lakehouse Iceberg REST

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

Ce point de terminaison sert de source unique d'informations fiables, 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 plus riche en fonctionnalités.

Avant de commencer

Avant de continuer, familiarisez-vous avec le catalogue d'exécution Lakehouse et la présentation 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 :

  • Effectuez 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
  • É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 :
  • 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 REST Apache Iceberg 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 Managed Service pour Apache Spark sur les versions d'image Compute Engine 2.3.16 et ultérieures.
  • 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 REST Apache Iceberg 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 les tables Apache Iceberg gérées par le point de terminaison du catalogue REST Apache Iceberg dans BigQuery.
  • Il est impossible d'interroger les tables de métadonnées Apache Iceberg (telles que .snapshots ou .files) 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 du point 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 la procédure générale à suivre lorsque vous utilisez le point de terminaison du catalogue REST Apache Iceberg dans le catalogue du runtime 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 Google Cloud Lakehouse d'accorder aux utilisateurs des autorisations sur des fichiers de données spécifiques.

Identifiants de l'utilisateur final

Console

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

    Accéder à Google Cloud 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 de catalogue REST Lakehouse gérées pour Apache Iceberg, 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 les buckets Cloud Storage multirégionaux aux États-Unis ou dans l'UE, spécifiez US ou EU pour vous assurer que le catalogue est accessible depuis les régions BigQuery correspondantes. Pour en savoir plus, consultez Régions du catalogue.

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.

Console

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

    Accéder à Google Cloud 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 Utilisateur d'objets de stockage sur votre bucket de stockage.

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 REST Apache Iceberg sur Managed Service pour Apache Spark, commencez par créer un cluster incluant le composant Apache 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 Managed Service pour Apache Spark.
  • DATAPROC_VERSION : version de l'image Managed Service pour Apache Spark (par exemple, 2.2).

Après avoir créé le cluster, configurez votre session Spark pour qu'elle utilise le point de terminaison du catalogue Apache Iceberg REST :

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 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/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 une valeur de 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 2.2.60 et ultérieures des environnements d'exécution Managed Service pour Apache Spark 2.2
  • Versions d'exécution 2.3.10 et ultérieures de 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 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.
  • 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 pas compatible avec Managed Service pour Apache Spark Trino.

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

Interroger des tables dans BigQuery

La façon dont vous interrogez les tables que vous créez via le point de terminaison du catalogue REST Apache Iceberg dans BigQuery dépend de l'utilisation d'un entrepôt de buckets Cloud Storage ou de la fédération BigQuery.

  • Entrepôt de buckets Cloud Storage : si vous avez configuré votre client avec un chemin d'entrepôt gs://, interrogez les tables depuis BigQuery à l'aide du nom en quatre parties (P.C.N.T) project.catalog.namespace.table. Pour en savoir plus sur la structure P.C.N.T, consultez Concepts du catalogue REST Iceberg. Le composant catalog correspond au nom de la ressource de catalogue d'exécution Lakehouse. Pour en savoir plus sur l'interrogation de tables, consultez Interroger une table.

  • Fédération BigQuery : si vous avez configuré votre client avec un chemin d'accès à l'entrepôt bq://, les tables que vous créez sont visibles dans BigQuery et peuvent être interrogées directement à l'aide du langage SQL BigQuery standard :

    SELECT * FROM `NAMESPACE_NAME.TABLE_NAME`;

    Remplacez les éléments suivants :

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

Utiliser la fédération de catalogues avec BigQuery

Pour en savoir plus sur la fédération de catalogues, consultez Concepts du catalogue REST Iceberg. Pour activer la fédération, configurez votre client avec le format d'entrepôt bq://projects/PROJECT_ID dans le champ WAREHOUSE_PATH des exemples de configuration du client dans Configurer l'application cliente. Vous pouvez également choisir d'inclure un emplacement BigQuery pour limiter les futures requêtes à un seul emplacement au format bq://projects/PROJECT_ID/locations/LOCATION.

Étant donné que ces ressources sont gérées par BigQuery, vous devez disposer des autorisations requises.

Une fois que vous avez configuré votre client pour la fédération, vous pouvez créer un espace de noms pour vos tables fédérées.

Spark

Pour utiliser la fédération de catalogue BigQuery, incluez les clauses LOCATION et DBPROPERTIES :

spark.sql("CREATE NAMESPACE IF NOT EXISTS NAMESPACE_NAME LOCATION 'gs://BUCKET_NAME/NAMESPACE_NAME' WITH DBPROPERTIES ('gcp-region' = 'LOCATION');")
spark.sql("USE NAMESPACE_NAME;")

Remplacez les éléments suivants :

  • NAMESPACE_NAME : nom de votre espace de noms.
  • BUCKET_NAME : bucket Cloud Storage que vous utilisez avec votre catalogue.
  • LOCATION : emplacement BigQuery. La valeur par défaut est la région multirégionale US.

Trino

Pour utiliser la fédération de catalogue BigQuery, incluez les propriétés LOCATION et gcp-region :

CREATE SCHEMA IF NOT EXISTS  CATALOG_NAME.SCHEMA_NAME WITH ( LOCATION = 'gs://BUCKET_NAME/SCHEMA_NAME', "gcp-region" = 'LOCATION');
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.
  • BUCKET_NAME : bucket Cloud Storage que vous utilisez avec votre catalogue.
  • LOCATION : emplacement BigQuery. La valeur par défaut est la région multirégionale US.

Tarifs

Pour en savoir plus sur les tarifs, consultez la page Tarifs de Google Cloud Lakehouse.

Étapes suivantes