自 2026 年 4 月 20 日起，BigLake 现已更名为 Lakehouse。BigLake metastore 现已更名为 Lakehouse 运行时目录。Lakehouse API、客户端库、CLI 命令和 IAM 名称保持不变，仍引用 BigLake。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

设置 Spark 和 Delta 表

本文档介绍了如何使用 Lakehouse 运行时目录配置 Apache Spark 以使用 Delta Lake 表。您将学习如何创建 Apache Hive 目录、配置 Spark 会话以连接到 metastore，以及运行工作负载以创建和注册 Delta 表，以便在 BigQuery 中查询。

准备工作

阅读关于 Hive 目录端点。
查看支持的存储格式和数据类型。
查看限制和注意事项。

登录您的 Google Cloud 账号。如果您是 Google Cloud的新用户，请创建一个账号，以评估我们的产品在实际场景中的表现。新客户还可以获得 300 美元的免费抵用金，用于运行、测试和部署工作负载。

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

所需的角色

如需获得使用 Lakehouse 运行时目录和 Delta 表所需的权限，请让您的管理员为您授予项目的以下 IAM 角色：

创建 Managed Service for Apache Spark 集群： Dataproc Editor (roles/dataproc.editor)
集群服务帐号：
- Dataproc Worker (roles/dataproc.worker)
- Storage Object User (roles/storage.objectUser)
- BigLake Editor (roles/biglake.editor)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
对所有 Lakehouse 运行时目录资源的写入权限： BigLake Editor (roles/biglake.editor)
对所有 Lakehouse 运行时目录资源的只读权限： BigLake Viewer (roles/biglake.viewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

如需相关说明，请参阅授予单个角色。

常规工作流程

如需将 Lakehouse 运行时目录与 Delta 表搭配使用，请按照以下工作流程操作：

创建 Lakehouse Hive 目录。
使用 Lakehouse metastore 客户端和 Delta Lake 依赖项配置 Spark 会话。
使用 Spark 在 Cloud Storage 中创建并填充 Delta 表，这会将它们注册到 metastore。
从 Apache Spark（读取和写入）或直接从 BigQuery（只读）查询 Delta 表。

创建 Lakehouse Hive 目录

如需将 Lakehouse 运行时目录与 Spark 和 Delta 表搭配使用，请创建 Hive 目录。

Lakehouse Hive 目录是 Hive 数据库的集合。在运行 Spark 作业之前，请创建一个目录以将其注册到 Lakehouse Metastore。该目录需要一个名称和一个 Cloud Storage 位置来存储数据。

控制台

在 Google Cloud 控制台中，打开 Lakehouse 页面。

前往 Lakehouse
点击创建目录 。
选择 Lakehouse 运行时目录 。
对于目录类型 ，选择 Hive Metastore 。
在选择 Cloud Storage 存储桶 字段中，输入目录的 Cloud Storage 存储桶名称。或者，点击浏览以选择或创建存储桶。
对于目录 ID，输入 Lakehouse Hive 目录的名称。
对于主要位置，请指定与存储桶相同的区域。
点击创建。

gcloud

如需创建 Hive 目录，请运行以下命令：

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

替换以下内容：

LAKEHOUSE_CATALOG_ID：Hive 目录名称。
GCS_WAREHOUSE_PATH：仓库数据的 Cloud Storage 路径。
PROJECT_ID：您的 Google Cloud 项目 ID。
REGION：metastore 的主要区域。对于单区域存储桶，此值与存储桶区域匹配。对于双区域或多区域存储桶，请为主要副本指定一个组成区域。另一个区域将成为辅助副本。
DESCRIPTION：目录的说明。

配置 Spark 以使用 Delta 表

如需将 Lakehouse 运行时目录与 Delta 表搭配使用，请使用 Lakehouse metastore 客户端工厂和 Delta Lake 扩展程序配置 Spark 会话。

spark-sql

使用 SSH 连接到 Managed Service for Apache Spark 集群的主节点。

在命令行中使用以下属性运行 spark-sql，以启动交互式 Spark SQL 会话：

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

会话启动后，Spark 会连接到 Lakehouse 运行时目录。

运行以下命令以创建和查询 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;

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LAKEHOUSE_CATALOG_ID：Hive 目录名称。
GCS_WAREHOUSE_PATH：存储仓库数据的 Cloud Storage 路径。

Jupyter 笔记本

在 Managed Service for Apache Spark 集群上运行 Jupyter 笔记本。
在控制台 Google Cloud 中，从Web 界面 标签页访问 Jupyter 网页界面。

在新的笔记本中，创建一个为 Delta Lake 配置的 Spark 会话并运行查询：

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()

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
GCS_WAREHOUSE_PATH：存储仓库数据的 Cloud Storage 路径。
LAKEHOUSE_CATALOG_ID：Hive 目录名称。

BigQuery 笔记本

在 Google Cloud 控制台中，前往 BigQuery。

前往 BigQuery
在探索器 窗格中，点击 + 添加 ，然后点击 Python 笔记本 。

在代码单元格中，使用 Delta 扩展程序和 Lakehouse 运行时目录属性配置 Managed Service for Apache Spark 会话：

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")

在另一个代码单元格中，创建数据库和 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()

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
GCS_WAREHOUSE_PATH：存储仓库数据的 Cloud Storage 路径。
LAKEHOUSE_CATALOG_ID：Hive 目录名称。

提交 Managed Service for Apache Spark 批量作业

您可以向 Managed Service for Apache Spark 提交 PySpark 批处理工作负载，以使用 Lakehouse 运行时目录创建和查询 Delta 表。

使用 PySpark 作业创建 Python 文件：

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()

替换以下内容：

PROJECT_ID：您的 Google Cloud 项目 ID。
LAKEHOUSE_CATALOG_ID：Hive 目录名称。
GCS_WAREHOUSE_PATH：存储仓库数据的 Cloud Storage 路径。

提交批量作业：
```
gcloud dataproc batches submit pyspark PYTHON_SCRIPT_FILE \
    --version=2.2 \
    --project=PROJECT_ID \
    --region=REGION \
    --deps-bucket=gs://CLOUD_STORAGE_BUCKET
```
替换以下内容：
- PYTHON_SCRIPT_FILE：PySpark 应用文件的本地或 Cloud Storage 路径。
- PROJECT_ID：您的项目 ID。
- REGION：运行批量作业的区域。
- CLOUD_STORAGE_BUCKET：用于暂存工作负载依赖项的 Cloud Storage 存储桶。

从 BigQuery 查询 Delta 表

在 Lakehouse 运行时目录中从 Spark 创建 Delta 表后，您可以从 BigQuery Studio 查询这些表。

从 BigQuery 在 Hive 目录端点中的 Delta 表上执行的查询是只读的。

在 Google Cloud 控制台中，前往 BigQuery。

前往 BigQuery
在查询编辑器中，输入以下语句：
```
SELECT * FROM `PROJECT_ID.LAKEHOUSE_CATALOG_ID.DATABASE_NAME.TABLE_NAME`;
```
替换以下内容：
- PROJECT_ID：您的项目 ID。
- LAKEHOUSE_CATALOG_ID：您的 Hive 目录名称。
- DATABASE_NAME：您的数据库名称。
- TABLE_NAME：您的 Delta 表名称。

限制

将 Delta 表与 Lakehouse 运行时目录 Hive 目录端点搭配使用时，存在以下限制：

BigQuery 中的只读查询：从 BigQuery 对 Delta 表执行的查询是只读的。使用 Apache Spark 执行数据修改、DML 操作和架构更改。
**GetHiveTable 上的占位符架构和真实架构检查**：对 Delta 表的 GetHiveTable 调用会返回占位符架构，而不是实际的表架构。如需检查 Delta 表的真实架构，请使用 Apache Spark。BigQuery 会计算适用于 Dremel 查询执行的修改后架构，该架构与真实的 Delta 表架构不完全匹配。
Hive 客户端不兼容：Hive 客户端（例如 Hive CLI）不支持使用 Lakehouse 运行时目录 Hive 端点的 Delta 表。请使用 Apache Spark 管理 Delta 表，并使用 Spark 或 BigQuery 查询这些表。
不支持目录管理的操作：Delta 表不支持目录管理模式。您无法使用独立 metastore DDL 创建 Delta 表。请改为在 Cloud Storage 中创建具有外部存储位置的 Delta 表（例如，使用 Apache Spark），并在目录中注册这些表。
BigQuery 外部 Delta 表限制： Lakehouse 运行时目录 Hive 端点使用与 BigQuery 外部 Delta Lake 表相同的底层查询引擎实现。所有外部 Delta Lake 表限制和 BigLake 表限制均适用。例如，不支持变更数据捕获 (CDC) 操作和 BigQuery Storage Read API，并且不支持 timestamp_ntz。

设置 Spark 和 Delta 表 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

所需的角色

常规工作流程

创建 Lakehouse Hive 目录

控制台

gcloud

配置 Spark 以使用 Delta 表

spark-sql

Jupyter 笔记本

BigQuery 笔记本

提交 Managed Service for Apache Spark 批量作业

从 BigQuery 查询 Delta 表

限制

后续步骤

设置 Spark 和 Delta 表