Depuis le 20 avril 2026, BigLake s'appelle désormais Lakehouse. BigLake Metastore s'appelle désormais le catalogue d'environnements d'exécution Lakehouse. Les noms des API Lakehouse, des bibliothèques clientes, des commandes CLI et d'IAM restent inchangés et font toujours référence à BigLake.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Configurer Spark avec des tables Delta

Ce document explique comment configurer Apache Spark avec le catalogue d'environnements d'exécution Lakehouse pour utiliser des tables Delta Lake. Vous apprendrez à créer un catalogue Apache Hive, à configurer des sessions Spark pour vous connecter au metastore et à exécuter des charges de travail afin de créer et d'enregistrer des tables Delta à interroger dans BigQuery.

Avant de commencer

Consultez À propos du point de terminaison du catalogue Hive.
Consultez Formats de stockage et types de données compatibles.
Consultez Limites et points à prendre en compte.

Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse, Managed Service for Apache Spark APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Verify that billing is enabled for your Google Cloud project.

Enable the Lakehouse, Managed Service for Apache Spark APIs, if any are not already enabled.

Roles required to enable APIs

Enable the APIs

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser le catalogue d'environnements d'exécution Lakehouse avec des tables Delta, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Créer un cluster Managed Service pour Apache Spark: Éditeur Dataproc (roles/dataproc.editor)
Compte de service du cluster :
- Nœud de calcul Dataproc (roles/dataproc.worker)
- Utilisateur d'objets Storage (roles/storage.objectUser)
- Éditeur BigLake (roles/biglake.editor)
- Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer)
Accès en écriture à toutes les ressources du catalogue d'environnements d'exécution Lakehouse : Éditeur BigLake (roles/biglake.editor)
Accès en lecture seule à toutes les ressources du catalogue d'environnements d'exécution Lakehouse: Lecteur BigLake (roles/biglake.viewer)

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.

Pour savoir comment procéder, consultez la section Attribuer un rôle unique.

Workflow général

Pour utiliser le catalogue d'environnements d'exécution Lakehouse avec des tables Delta, procédez comme suit :

Créez un catalogue Hive Lakehouse.
Configurez votre session Spark avec le client metastore Lakehouse et les dépendances Delta Lake.
Créez et remplissez des tables Delta dans Cloud Storage à l'aide de Spark, qui les enregistre dans le metastore.
Interrogez les tables Delta à partir d'Apache Spark (lecture et écriture) ou directement depuis BigQuery (lecture seule).

Créer un catalogue Hive Lakehouse

Pour utiliser le catalogue d'environnements d'exécution Lakehouse avec Spark et des tables Delta, créez un catalogue Hive.

Un catalogue Hive Lakehouse est un ensemble de bases de données Hive. Avant d'exécuter des jobs Spark, créez un catalogue pour l'enregistrer dans Lakehouse Metastore. Le catalogue nécessite un nom et un emplacement Cloud Storage pour les données.

Console

Dans la Google Cloud console, ouvrez la page Lakehouse.

Accéder à Lakehouse
Cliquez sur Create catalog (Créer un catalogue).
Sélectionnez Lakehouse runtime catalog (Catalogue d'environnements d'exécution Lakehouse).
Pour Catalog type (Type de catalogue), sélectionnez Hive Metastore.
Dans le champ Select a Cloud Storage bucket (Sélectionner un bucket Cloud Storage), saisissez le nom du bucket Cloud Storage de votre catalogue. Vous pouvez également cliquer sur Browse (Parcourir) pour choisir ou créer un bucket.
Pour Catalog ID (ID du catalogue), saisissez un nom pour votre catalogue Hive Lakehouse.
Pour Primary location (Emplacement principal), spécifiez la même région que votre bucket.
Cliquez sur Create (Créer).

gcloud

Pour créer un catalogue Hive, exécutez la commande suivante :

gcloud biglake hive catalogs create LAKEHOUSE_CATALOG_ID \
    --project=PROJECT_ID \
    --location-uri="gs://GCS_WAREHOUSE_PATH" \
    --primary-location=REGION \
    --description="DESCRIPTION"

Remplacez les éléments suivants :

LAKEHOUSE_CATALOG_ID : nom du catalogue Hive.
GCS_WAREHOUSE_PATH: chemin d'accès Cloud Storage à vos données d'entrepôt.
PROJECT_ID : ID de votre Google Cloud projet.
REGION : région principale du metastore. Pour les buckets à région unique, cette valeur correspond à la région du bucket. Pour les buckets birégionaux ou multirégionaux, spécifiez une région constitutive pour l'instance répliquée principale. L'autre région devient l'instance répliquée secondaire.
DESCRIPTION : description du catalogue.

Configurer Spark pour utiliser des tables Delta

Pour utiliser le catalogue d'environnements d'exécution Lakehouse avec des tables Delta, configurez votre session Spark avec la fabrique de clients metastore Lakehouse et les extensions Delta Lake.

spark-sql

Utilisez SSH pour vous connecter au nœud principal de votre cluster Managed Service pour Apache Spark.

Exécutez spark-sql sur la ligne de commande avec les propriétés suivantes pour démarrer une session Spark SQL interactive :

spark-sql \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=org.apache.spark.sql.delta.catalog.DeltaCatalog \
    --conf spark.hive.metastore.client.factory.class=com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory \
    --conf spark.hive.metastore.blms.project.id=PROJECT_ID \
    --conf spark.hive.metastore.blms.catalog.default=LAKEHOUSE_CATALOG_ID \
    --conf spark.hive.metastore.warehouse.dir=gs://GCS_WAREHOUSE_PATH

Une fois la session démarrée, Spark se connecte au catalogue d'environnements d'exécution Lakehouse.

Exécutez les commandes suivantes pour créer et interroger des ressources Delta :

-- Show all the databases in the current project.
SHOW DATABASES;

-- Create a database.
CREATE DATABASE spark_delta_blms_database;

-- Create a Delta data source table.
CREATE TABLE spark_delta_blms_database.delta_quick_start (id INT, name STRING) USING DELTA;

-- Insert data into the table.
INSERT INTO TABLE spark_delta_blms_database.delta_quick_start VALUES (1, 'my-first-user');

-- Query the Delta table.
SELECT * FROM spark_delta_blms_database.delta_quick_start;

Remplacez les éléments suivants :

PROJECT_ID : ID de votre Google Cloud projet.
LAKEHOUSE_CATALOG_ID : nom du catalogue Hive.
GCS_WAREHOUSE_PATH: chemin d'accès Cloud Storage où sont stockées vos données d'entrepôt.

Notebook Jupyter

Exécutez un notebook Jupyter sur un cluster Managed Service pour Apache Spark.
Accédez à l'interface Web Jupyter depuis l'onglet Web interfaces (Interfaces Web) de la page d'informations du cluster dans la Google Cloud console.

Dans un nouveau notebook, créez une session Spark configurée pour Delta Lake et exécutez des requêtes :

from pyspark.sql import SparkSession

# If a Spark session exists, stop it first by running spark.stop()
spark = SparkSession.builder\
    .master("local")\
    .appName("Lakehouse runtime catalog Delta tutorial")\
    .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")\
    .config("spark.sql.catalog.spark_catalog", "org.apache.spark.sql.delta.catalog.DeltaCatalog")\
    .config("spark.hive.metastore.client.factory.class", "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory")\
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")\
    .config("spark.hive.metastore.warehouse.dir", "gs://GCS_WAREHOUSE_PATH")\
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")\
    .getOrCreate()

# Show all the databases.
df = spark.sql("SHOW DATABASES;")
df.show()

# Create a database.
spark.sql("CREATE DATABASE jupyter_delta_blms_db")

# Create a Delta data source table.
spark.sql("CREATE TABLE jupyter_delta_blms_db.delta_table(id INT, name STRING) USING DELTA")

# Insert data into the table.
spark.sql("INSERT INTO TABLE jupyter_delta_blms_db.delta_table VALUES (1, 'my-first-user');")

# Query from table.
spark.sql("SELECT * FROM jupyter_delta_blms_db.delta_table;").show()

Remplacez les éléments suivants :

PROJECT_ID : ID de votre Google Cloud projet.
GCS_WAREHOUSE_PATH: chemin d'accès Cloud Storage où sont stockées vos données d'entrepôt.
LAKEHOUSE_CATALOG_ID : nom du catalogue Hive.

Notebook BigQuery

Dans la Google Cloud console, accédez à BigQuery.

Accéder à BigQuery
Dans le volet Explorer (Explorateur), cliquez sur + ADD (+ AJOUTER), puis sur Python notebook (Notebook Python).

Dans une cellule de code, configurez la session Managed Service pour Apache Spark avec les extensions Delta et les propriétés du catalogue d'environnements d'exécution Lakehouse :

from google.cloud.dataproc_spark_connect import DataprocSparkSession
from google.cloud.dataproc_v1 import Session
import os

os.environ['DATAPROC_SPARK_CONNECT_DEFAULT_DATASOURCE'] = ""

session = Session()
session.environment_config.execution_config.ttl = {"seconds": 864000}
session.runtime_config.version = "2.3"
session.runtime_config.properties = {
 "spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
 "spark.sql.catalog.spark_catalog": "org.apache.spark.sql.delta.catalog.DeltaCatalog",
 "spark.hive.metastore.blms.project.id": "PROJECT_ID",
 "spark.hive.metastore.blms.catalog.default": "LAKEHOUSE_CATALOG_ID",
 "spark.hive.metastore.warehouse.dir": "gs://GCS_WAREHOUSE_PATH",
 "spark.hive.metastore.client.factory.class": "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory",
 "spark.sql.catalogImplementation": "hive"
}

spark = DataprocSparkSession.builder.dataprocSessionConfig(session).getOrCreate()
print("Spark session created successfully")

Dans une autre cellule de code, créez une base de données et une table Delta :

# Create a database
spark.sql("CREATE DATABASE bq_spark_delta_database;")

# Create a Delta data source table
spark.sql("CREATE TABLE bq_spark_delta_database.delta_quick_start (id INT, name STRING) USING DELTA;")

# Insert data into the table
spark.sql("INSERT INTO TABLE bq_spark_delta_database.delta_quick_start VALUES (1, 'my-first-user');")

# Query from table
spark.sql("SELECT * FROM bq_spark_delta_database.delta_quick_start;").show()

Remplacez les éléments suivants :

PROJECT_ID : ID de votre Google Cloud projet.
GCS_WAREHOUSE_PATH: chemin d'accès Cloud Storage où sont stockées vos données d'entrepôt.
LAKEHOUSE_CATALOG_ID : nom du catalogue Hive.

Envoyer un job par lot Managed Service pour Apache Spark

Vous pouvez envoyer une charge de travail par lot PySpark à Managed Service pour Apache Spark afin de créer et d'interroger des tables Delta avec le catalogue d'environnements d'exécution Lakehouse.

Créez un fichier Python avec un job PySpark :

from pyspark.sql import SparkSession

spark = (
    SparkSession.builder.appName("Lakehouse runtime catalog Delta tutorial")
    .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")
    .config("spark.sql.catalog.spark_catalog", "org.apache.spark.sql.delta.catalog.DeltaCatalog")
    .config(
        "spark.hive.metastore.client.factory.class",
        "com.google.cloud.bigquery.metastore.client.BigLakeMetastoreClientFactory",
    )
    .config("spark.hive.metastore.blms.project.id", "PROJECT_ID")
    .config("spark.hive.metastore.blms.catalog.default", "LAKEHOUSE_CATALOG_ID")
    .config(
        "spark.hive.metastore.warehouse.dir",
        "gs://GCS_WAREHOUSE_PATH",
    )
    .enableHiveSupport()
    .getOrCreate()
)

# Show all the databases.
spark.sql("SHOW DATABASES;").show()

# Create a database.
spark.sql("CREATE DATABASE dp_serverless_delta_db")

# Create a Delta data source table.
spark.sql(
    "CREATE TABLE dp_serverless_delta_db.delta_table(id INT, name STRING) USING DELTA"
)

# Insert data into the table.
spark.sql("INSERT INTO TABLE dp_serverless_delta_db.delta_table VALUES (1, 'my-first-user');")

# Query from table.
spark.sql("SELECT * FROM dp_serverless_delta_db.delta_table;").show()

Remplacez les éléments suivants :

PROJECT_ID: ID de votre Google Cloud projet.
LAKEHOUSE_CATALOG_ID : nom du catalogue Hive.
GCS_WAREHOUSE_PATH: chemin d'accès Cloud Storage où sont stockées vos données d'entrepôt.

Envoyez le job par lot :
```
gcloud dataproc batches submit pyspark PYTHON_SCRIPT_FILE \
    --version=2.2 \
    --project=PROJECT_ID \
    --region=REGION \
    --deps-bucket=gs://CLOUD_STORAGE_BUCKET
```
Remplacez les éléments suivants :
- PYTHON_SCRIPT_FILE: chemin d'accès local ou Cloud Storage au fichier d'application PySpark.
- PROJECT_ID : ID du projet.
- REGION : région dans laquelle exécuter le job par lot.
- CLOUD_STORAGE_BUCKET: bucket Cloud Storage pour la préparation des dépendances de la charge de travail.

Interroger des tables Delta depuis BigQuery

Après avoir créé des tables Delta à partir de Spark dans le catalogue d'environnements d'exécution Lakehouse, vous pouvez les interroger depuis BigQuery Studio.

Les requêtes exécutées à partir de BigQuery sur des tables Delta dans le point de terminaison du catalogue Hive sont en lecture seule.

Dans la Google Cloud console, accédez à BigQuery.

Accéder à BigQuery
Dans l'éditeur de requête, saisissez l'instruction suivante :
```
SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.DATABASE_NAME.TABLE_NAME`;
```
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet.
- LAKEHOUSE_CATALOG_ID : nom de votre catalogue Hive.
- DATABASE_NAME : nom de votre base de données.
- TABLE_NAME : nom de votre table Delta.

Limites

Lorsque vous utilisez des tables Delta avec le point de terminaison du catalogue Hive du catalogue d'environnements d'exécution Lakehouse, les limites suivantes s'appliquent :

Requêtes en lecture seule dans BigQuery : les requêtes sur les tables Delta à partir de BigQuery sont en lecture seule. Effectuez des modifications de données, des opérations LMD et des modifications de schéma à l'aide d'Apache Spark.
Schéma d'espace réservé sur GetHiveTable et inspection du schéma réel : GetHiveTable appels pour les tables Delta renvoient un schéma d'espace réservé au lieu de le schéma de table réel. Pour inspecter le schéma réel d'une table Delta, utilisez Apache Spark. BigQuery calcule un schéma modifié adapté à l'exécution de requêtes Dremel, qui ne correspond pas exactement au schéma de table Delta réel.
Incompatibilité du client Hive : les clients Hive (tels que l'interface CLI Hive) ne sont pas compatibles avec les tables Delta avec le point de terminaison Hive du catalogue d'environnements d'exécution Lakehouse. Utilisez Apache Spark pour gérer les tables Delta, et Spark ou BigQuery pour les interroger.
Opérations gérées par le catalogue non compatibles : le mode géré par le catalogue n'est pas compatible avec les tables Delta. Vous ne pouvez pas créer de table Delta à l'aide du LDD de metastore autonome. Créez plutôt des tables Delta avec des emplacements de stockage externes dans Cloud Storage (par exemple, à l'aide d'Apache Spark) et enregistrez-les dans le catalogue.
Limites des tables Delta externes BigQuery : le point de terminaison Hive du catalogue d'environnements d'exécution Lakehouse utilise la même implémentation de moteur de requête sous-jacente que les tables Delta Lake externes BigQuery. Toutes les limites des tables Delta Lake externes et des tables BigLake s'appliquent. Par exemple, les opérations de capture de données modifiées (CDC) et l'API BigQuery Storage Read ne sont pas compatibles, et timestamp_ntz n'est pas accepté.

Configurer Spark avec des tables Delta Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Avant de commencer

Rôles requis

Workflow général

Créer un catalogue Hive Lakehouse

Console

gcloud

Configurer Spark pour utiliser des tables Delta

spark-sql

Notebook Jupyter

Notebook BigQuery

Envoyer un job par lot Managed Service pour Apache Spark

Interroger des tables Delta depuis BigQuery

Limites

Étape suivante

Configurer Spark avec des tables Delta