Utiliser le catalogue BigLake Metastore Iceberg REST

Le catalogue Apache Iceberg REST dans BigLake Metastore est la méthode recommandée pour utiliser BigLake Metastore pour les nouveaux workflows. Il crée une interopérabilité entre vos moteurs de requête en offrant une source unique de référence pour toutes vos données Iceberg. Il permet aux moteurs de requête, tels qu'Apache Spark, de découvrir, de lire les métadonnées et de gérer les tables Iceberg de manière cohérente.

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 précis des accès, ainsi que la réplication interrégionale et la reprise après sinistre.

En revanche, le catalogue 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 BigLake Metastore.

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

  2. Enable the BigLake API.

    Roles required to enable APIs

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

    Enable the API

Rôles requis

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

  • 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
  • É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 :

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 catalogue REST Iceberg est soumis aux limitations suivantes :

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

Ressources du catalogue

Le catalogue Apache Iceberg REST dans BigLake Metastore utilise une hiérarchie de ressources pour organiser vos données.

Ressources du catalogue Apache Iceberg REST

Le tableau suivant fournit un aperçu des ressources utilisées par le catalogue Apache Iceberg REST dans BigLake Metastore.

Ressource Description
Catalogue Un catalogue est un conteneur de premier niveau qui vous permet d'organiser les espaces de noms et les tables en groupes logiques en les divisant en différents catalogues.
Espace de noms Il s'agit d'un regroupement logique utilisé pour organiser les tables dans un catalogue. Il fonctionne comme des bases de données, des schémas ou des répertoires.
Table Les tables contiennent des définitions de lignes et de colonnes pouvant faire l'objet de requêtes.

Catalogues compatibles

Lorsque vous configurez votre client, vous spécifiez un emplacement d'entrepôt. Ce choix détermine le fonctionnement de votre catalogue et son intégration à d'autres services Google Cloud.

Type de catalogue Description
Bucket Cloud Storage Toutes les données d'un catalogue sont stockées dans un seul bucket Cloud Storage. Si les données sont partagées entre plusieurs buckets, plusieurs catalogues sont nécessaires.
Fédération BigQuery Vous permet d'utiliser le catalogue REST Iceberg pour gérer et interroger les tables visibles par BigQuery. Pour en savoir plus, consultez Utiliser la fédération de catalogues avec BigQuery.

Détails de l'entrepôt du catalogue

Recommandé

  • Entrepôt de buckets Cloud Storage (gs://) : il s'agit de l'approche standard, où le catalogue gère directement les métadonnées et les fichiers de données Iceberg dans un bucket Cloud Storage que vous spécifiez. Cette option vous permet de contrôler directement la mise en page de vos données et est compatible avec la distribution d'identifiants pour un contrôle des accès précis. Cela vous permet de créer et de gérer des tables BigLake pour Apache Iceberg.

    Par exemple, si vous avez créé votre bucket pour stocker votre catalogue et que vous l'avez nommé iceberg-bucket, le nom de votre catalogue et celui de votre bucket sont tous les deux iceberg-bucket. Vous l'utiliserez plus tard pour interroger votre catalogue dans BigQuery à l'aide de la syntaxe P.C.N.T. Par exemple : my-project.biglake-catalog-id.quickstart_namespace.quickstart_table.

Ancien

  • Fédération BigQuery (bq://) : cette approche vous permet d'utiliser le catalogue REST Iceberg pour gérer et interroger les tables visibles par BigQuery, sans avoir à créer de ressource de catalogue. Pour en savoir plus, consultez Utiliser la fédération de catalogues avec BigQuery.

Structure de nommage des P.C.N.T

Lorsque vous interrogez des tables BigLake Metastore depuis BigQuery, vous utilisez une structure de nommage en quatre parties, souvent appelée P.C.N.T :

  • Projet : ID du projet Google Cloud propriétaire du catalogue.
  • Catalogue : nom du catalogue BigLake Metastore.
  • Espace de noms : espace de noms Iceberg (équivalent à un ensemble de données BigQuery).
  • Table : nom de la table.

Par exemple, my-project.biglake-catalog-id.my-namespace.my-table.

Configurer le catalogue Iceberg REST

Voici la procédure générale à suivre lorsque vous utilisez le catalogue Apache Iceberg REST dans BigLake Metastore :

  1. Comprendre et choisir l'emplacement de l'entrepôt de catalogues, 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 catalogue 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 de métastore BigLake de contrôler les autorisations directement sur les ressources de métastore BigLake. Les utilisateurs du catalogue n'ont ainsi pas besoin d'avoir un accès direct aux buckets Cloud Storage. Il permet aux administrateurs BigLake d'accorder des autorisations aux utilisateurs sur des fichiers de données spécifiques.

Identifiants de l'utilisateur final

Console

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

    Accéder à BigLake

  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

Utilisez la commande gcloud beta biglake iceberg catalogs create.

gcloud beta 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 tables BigLake 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 .

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 catalogue 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 catalogue Iceberg REST.

Console

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

    Accéder à BigLake

  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 avec ou sans distribution d'identifiants.

Cluster

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

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

Remplacez les éléments suivants :

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

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', '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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue REST Iceberg.
  • APP_NAME : nom de votre session Spark.
  • 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 catalogue REST Iceberg, qui peut être différent du projet propriétaire du bucket Cloud Storage. Pour en savoir plus sur la configuration du projet lorsque vous utilisez une API REST, consultez Paramètres système.

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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

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

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

Sans serveur

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

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=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,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false"

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 Dataproc.
  • RUNTIME_VERSION : version d'exécution Serverless pour Apache Spark (par exemple, 2.2).
  • CATALOG_NAME : nom de votre catalogue REST Iceberg.
  • 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 catalogue Iceberg REST avec la valeur vended-credentials en ajoutant la ligne suivante aux configurations Serverless pour Apache Spark : 

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

Exemple avec la distribution d'identifiants

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

gcloud dataproc batches submit pyspark PYSPARK_FILE \
    --project=PROJECT_ID \
    --region=REGION \
    --version=RUNTIME_VERSION \
    --properties="\
    spark.sql.defaultCatalog=CATALOG_NAME,\
    spark.sql.catalog.CATALOG_NAME=org.apache.iceberg.spark.SparkCatalog,\
    spark.sql.catalog.CATALOG_NAME.type=rest,\
    spark.sql.catalog.CATALOG_NAME.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    spark.sql.catalog.CATALOG_NAME.warehouse=gs://CLOUD_STORAGE_BUCKET_NAME,\
    spark.sql.catalog.CATALOG_NAME.header.x-goog-user-project=PROJECT_ID,\
    spark.sql.catalog.CATALOG_NAME.rest.auth.type=org.apache.iceberg.gcp.auth.GoogleAuthManager,\
    spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions,\
    spark.sql.catalog.CATALOG_NAME.rest-metrics-reporting-enabled=false,
    spark.sql.catalog.CATALOG_NAME.header.X-Iceberg-Access-Delegation=vended-credentials"

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

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

  • Runtimes Serverless pour Apache Spark 2.2.60 et versions ultérieures
  • Environnements d'exécution Serverless pour Apache Spark 2.3.10 et versions ultérieures

Trino

Pour utiliser Trino avec le catalogue Iceberg REST, créez un cluster Dataproc avec le composant Trino et configurez les propriétés du catalogue à l'aide de l'option gcloud dataproc clusters create --properties. L'exemple suivant crée un catalogue Trino nommé CATALOG_NAME :

gcloud dataproc clusters create CLUSTER_NAME \
    --enable-component-gateway \
    --region=REGION \
    --image-version=DATAPROC_VERSION \
    --network=NETWORK_ID \
    --optional-components=TRINO \
    --properties="\
    trino-catalog:CATALOG_NAME.connector.name=iceberg,\
    trino-catalog:CATALOG_NAME.iceberg.catalog.type=rest,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.uri=https://biglake.googleapis.com/iceberg/v1/restcatalog,\
    trino-catalog:CATALOG_NAME.iceberg.rest-catalog.warehouse=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 Dataproc.
  • DATAPROC_VERSION : version de l'image Dataproc, par exemple 2.2.
  • NETWORK_ID : ID du réseau du cluster. Pour en savoir plus, consultez Configuration du réseau du cluster Dataproc.
  • CATALOG_NAME : nom de votre catalogue Trino utilisant le catalogue Iceberg REST.
  • 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 BigLake Metastore.

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

trino --catalog=CATALOG_NAME

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

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

Configurer avec la distribution d'identifiants

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

Iceberg 1.10 ou version ultérieure

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', '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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue REST Iceberg.
  • APP_NAME : nom de votre session Spark.
  • 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 catalogue 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 catalogue 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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f'spark.sql.catalog.{catalog_name}.rest.auth.type', 'org.apache.iceberg.gcp.auth.GoogleAuthManager') \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

Versions précédentes d'Iceberg

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

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

catalog_name = "CATALOG_NAME"
spark = SparkSession.builder.appName("APP_NAME") \
  .config('spark.jars.packages', 'org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.9.1,org.apache.iceberg:iceberg-gcp-bundle:1.9.1') \
  .config(f'spark.sql.catalog.{catalog_name}', 'org.apache.iceberg.spark.SparkCatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.type', 'rest') \
  .config(f'spark.sql.catalog.{catalog_name}.uri', 'https://biglake.googleapis.com/iceberg/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', '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}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

Remplacez les éléments suivants :

  • CATALOG_NAME : nom de votre catalogue REST Iceberg.
  • APP_NAME : nom de votre session Spark.
  • 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 catalogue 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 catalogue 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/v1/restcatalog') \
  .config(f'spark.sql.catalog.{catalog_name}.warehouse', 'gs://CLOUD_STORAGE_BUCKET_NAME') \
  .config(f'spark.sql.catalog.{catalog_name}.header.x-goog-user-project', 'PROJECT_ID') \
  .config(f"spark.sql.catalog.{catalog_name}.token", "TOKEN") \
  .config(f"spark.sql.catalog.{catalog_name}.oauth2-server-uri", "https://oauth2.googleapis.com/token") \
  .config(f'spark.sql.catalog.{catalog_name}.io-impl', 'org.apache.iceberg.gcp.gcs.GCSFileIO') \
  .config(f'spark.sql.catalog.{catalog_name}.header.X-Iceberg-Access-Delegation','vended-credentials') \
  .config(f'spark.sql.catalog.{catalog_name}.rest-metrics-reporting-enabled', 'false') \
  .config('spark.sql.extensions', 'org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions') \
  .config('spark.sql.defaultCatalog', 'CATALOG_NAME') \
  .getOrCreate()

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

Créer un espace de noms 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.

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 catalogue Iceberg REST.
  • 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 catalogue REST 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. Le composant catalog correspond au nom de la ressource de catalogue BigLake Metastore. Pour en savoir plus, 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 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

Vous pouvez utiliser l'interface du catalogue REST Iceberg pour gérer et interroger les tables visibles par BigQuery. Les catalogues de fédération BigQuery ne vous obligent pas à créer une ressource de catalogue. Vous pouvez les utiliser dans n'importe quel projet pour lequel l'API BigQuery est activée. Cela vous permet :

Étant donné que ces ressources sont gérées par BigQuery, vous devez disposer des autorisations requises applicables. La distribution d'identifiants n'est pas compatible avec les catalogues fédérés.

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 Utiliser le catalogue REST Iceberg. Vous pouvez également choisir d'inclure un emplacement BigQuery pour limiter les futures requêtes à un seul emplacement en utilisant le format bq://projects/PROJECT_ID/locations/LOCATION.

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 catalogues 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 catalogue Iceberg REST.
  • 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 BigLake.

Étapes suivantes