作者：Qi Yu
最后更新：2026-01-23

概述

在本教程中，您将学习如何配置和使用 Gravitino Lance REST 服务。完成本指南后，您将拥有一个功能完整的 Lance REST 服务，使 Lance 客户端能够通过 HTTP API 与 Gravitino 交互。

Gravitino Lance REST 服务为管理 Lance 数据集提供 RESTful 接口，实现标准的 Lance REST API。它充当集中式 catalog 服务，允许 Lance 客户端（如 Spark 和 Ray）发现和访问由 Gravitino 管理的 Lance 数据集。

核心概念：

• Lance REST catalog：用于 Lance 数据集操作的标准 HTTP API 规范
• Gravitino Lance REST 服务：实现 Lance REST API 并与 Gravitino 的元数据系统集成
• 统一元数据：在 Gravitino 中存储 Lance 数据集元数据，实现集中治理

REST 端点基础路径为 http://<host>:<port>/lance/。

前提条件

开始本教程之前，您需要：

系统要求：

• Linux 或 macOS 操作系统，具有出站互联网访问权限用于下载
• Python 环境（3.10+）用于运行 PySpark 或 Ray 客户端

必需组件：

• 已安装并配置的 Gravitino 服务器（参见 02-setup-guide/README.md）

可选组件：

• 带有 Lance 运行时 JAR 的 Apache Spark，用于客户端验证（推荐用于测试）
• Ray 框架，用于分布式 Lance 数据处理

继续之前，请验证您的 Python 安装并安装所需包：

python --version
pip install pyspark==3.5.0 lance-ray==0.1.0 lance-namespace

架构概述：

设置

步骤 1：启动带有 Lance REST 服务的 Gravitino 服务器

如果您希望将 Lance REST 服务嵌入到完整的 Gravitino 服务器中（包括 Web UI、统一 REST API 等），请使用此方法。

配置 Lance REST 作为辅助服务

1. 安装 Gravitino 服务器发行版

按照之前的教程 02-setup-guide/README.md 下载或构建 Gravitino 服务器包。

2. 启用 Lance REST 作为辅助服务

修改 conf/gravitino.conf 以启用 lance-rest 服务并进行配置：

# 启用 Lance REST 服务
gravitino.auxService.names = lance-rest
gravitino.lance-rest.httpPort = 9101
gravitino.lance-rest.host = 0.0.0.0
gravitino.lance-rest.namespace-backend = gravitino
gravitino.lance-rest.gravitino-uri = http://localhost:8090
gravitino.lance-rest.gravitino-metalake = lance_metalake

注意：当您访问 Lance REST 服务时，lance_metalake 应该在 Gravitino 中存在。如果不存在，您可以在启动 Gravitino 服务器后通过 Gravitino REST API 或 Web UI 创建它。

3. 启动 Gravitino 服务器

./bin/gravitino.sh start

4. 创建 Metalake（如果不存在）

curl -X POST -H "Content-Type: application/json" \
  -d '{"name":"lance_metalake","comment":"comment"}' \
  http://localhost:8090/api/metalakes

5. 检查服务器日志（可选）

tail -f logs/gravitino-server.log

步骤 2：验证 Lance REST 端点并创建 catalog namespace

测试服务端点

您可以通过以下命令验证服务是否正在运行：

curl -X GET http://localhost:9101/lance/v1/namespace/$/list \
  -H 'Content-Type: application/json'

成功时，您应该看到包含 namespace 信息的 JSON 响应。

创建 catalog namespace

创建一个 catalog namespace（例如 lance_catalog），它将用于包含您的 Lance Schema 和 Table：

curl -X POST http://localhost:9101/lance/v1/namespace/lance_catalog/create \
  -H 'Content-Type: application/json' \
  -d '{
    "id": ["lance_catalog"],
    "mode": "exist_ok"
  }'

如果成功，它会返回 namespace 信息。

步骤 3：从 Spark 中连接

配置您的 PySpark 会话以使用 Lance REST catalog。

配置 Spark

前提条件：

• 安装 pyspark：pip install pyspark==3.5.0
• 下载与您的 Spark 版本匹配的 lance-spark bundle jar（例如 lance-spark-bundle-3.5_2.12-0.0.15.jar）

执行示例操作

运行以下 Python 脚本：

from pyspark.sql import SparkSession
import os

# 设置 lance-spark bundle 的路径
os.environ["PYSPARK_SUBMIT_ARGS"] = (
    "--jars /path/to/lance-spark-bundle-3.5_2.12-0.0.15.jar "
    "--conf \"spark.driver.extraJavaOptions=--add-opens=java.base/sun.nio.ch=ALL-UNNAMED\" "
    "--conf \"spark.executor.extraJavaOptions=--add-opens=java.base/sun.nio.ch=ALL-UNNAMED\" "
    "--master local[1] pyspark-shell"
)

spark = SparkSession.builder \
    .appName("lance_rest_demo") \
    .config("spark.sql.catalog.lance", "com.lancedb.lance.spark.LanceNamespaceSparkCatalog") \
    .config("spark.sql.catalog.lance.impl", "rest") \
    .config("spark.sql.catalog.lance.uri", "http://localhost:9101/lance") \
    .config("spark.sql.catalog.lance.parent", "lance_catalog") \
    .config("spark.sql.defaultCatalog", "lance") \
    .getOrCreate()

# 创建 schema 和 table
spark.sql("CREATE DATABASE IF NOT EXISTS demo_schema")
spark.sql("""
    CREATE TABLE demo_schema.test_table (id INT, value STRING)
    USING lance
    LOCATION '/tmp/lance_catalog/demo_schema/test_table'
""")

# 插入和查询数据
spark.sql("INSERT INTO demo_schema.test_table VALUES (1, 'test')")
spark.sql("SELECT * FROM demo_schema.test_table").show()

步骤 4：使用 Ray 连接

您还可以使用 Ray 与 Lance Ray 集成来访问 Spark 创建的数据。

使用 Lance REST catalog 配置 Ray

前提条件：

• 安装所需包：pip install lance-ray==0.1.0 lance-namespace

执行示例操作

import ray
import lance_namespace as ln
from lance_ray import read_lance, write_lance

ray.init()

# 连接到 Lance REST
namespace = ln.connect("rest", {"uri": "http://localhost:9101/lance"})

# 读取 Spark 创建的 table
# 注意：Table ID 是 [catalog, schema, table]
ds = read_lance(namespace=namespace, table_id=["lance_catalog", "demo_schema", "test_table"])
print(f"Row count: {ds.count()}")
ds.show()

# 执行过滤操作
result = ds.filter(lambda row: row["id"] < 100).count()
print(f"Filtered row count: {result}")

故障排除

常见问题及其解决方案：

服务连接问题：

• 服务启动失败：检查 logs/gravitino-server.log 中的启动错误和配置问题
• 连接被拒绝：验证 gravitino.lance-rest.httpPort（默认 9101）是否开放且可访问
• curl 返回 404：确认 Lance REST 基础路径是 /lance，端口与配置匹配

客户端连接问题：

• Spark ClassNotFoundException：确保 lance-spark-bundle jar 在 PYSPARK_SUBMIT_ARGS 或 --jars 中正确引用
• Namespace 未找到：记住在创建 Schema 或 Table 之前创建父 catalog namespace（例如 lance_catalog）
• Ray 连接错误：验证 lance-ray 和 lance-namespace 包已安装，REST 端点可访问

配置问题：

• Metalake 未找到：确保 gravitino.lance-rest.gravitino-metalake 中指定的 metalake 在 Gravitino 中存在
• 权限错误：检查 Gravitino 服务器是否对配置的存储位置具有适当的访问权限

恭喜

您已成功完成 Gravitino Lance REST 服务配置！

您现在拥有一个功能完整的 Lance REST 服务，包括：

• 在端口 9101 上运行的已配置 Lance REST 端点
• 为组织 Lance 数据集配置的 catalog namespace
• 通过 Apache Spark 和 Ray 验证的客户端连接
• 对跨不同计算引擎的 Lance 数据集操作的理解

进一步阅读

有关更高级配置和详细文档：

• 查看 Lance REST 服务文档 了解完整的 API 详细信息
• 查看 Lance REST 集成指南 了解兼容性矩阵和高级配置
• 了解更多关于 Lance 格式 及其功能

下一步

• 继续阅读 Spark ETL
• 关注并收藏 Apache Gravitino 仓库

---

Apache Gravitino 正在快速发展，本文基于最新版本 1.1.0 编写。如果您遇到问题，请参考官方文档或在 GitHub 上提交问题。