1. 概览 #

Apache® Gravitino Lance REST Catalog（以下简称“Lance REST 服务”）提供一组兼容 Lance Namespace REST 规范的 HTTP API，用于管理 命名空间（Namespace） 与 表（Table） 的元数据。

Apache Gravitino, the names of other Apache projects, and the ASF logo are either registered trademarks or trademarks of the Apache Software Foundation in the United States and/or other countries.

典型场景包括：

• 在多引擎/多任务系统中，以统一 REST 入口管理 Lance 表的元数据
• 在对象存储（如 TOS）中已存在数据目录的情况下，通过“注册表”方式完成纳管
• 在自动化接入流程中，进行幂等创建、存在性校验、元数据查询与下线清理

2. 路径与标识符约定 #

2.1 Base URL #

服务的 REST 根路径固定包含 /lance，接口路径以 /lance/v1 开头：

• Base URL：https://{endpoint}/lance
• API 前缀：/lance/v1/...

2.2 NamespaceId 与 TableId #

Lance REST 在路径中使用字符串 id 表示命名空间或表，默认使用分隔符（delimiter）$：

• namespaceId：
  • 一级：{catalog}
  • 二级：{catalog}${schema}
• tableId：{catalog}${schema}${table}

分隔符可通过 query 参数 delimiter 传入（默认 $）。

2.3 URL 编码 #

$、@、# 等字符在 URL path 中需要进行百分号编码：

• $ → %24
• @ → %40
• # → %23

例如：demo_catalog$demo_schema 需处理为： demo_catalog%24demo_schema

3. 使用前准备 #

3.1 获取服务 Endpoint 与 Region #

你需要获取：

• 服务访问端点（Endpoint）
• Region（如 cn-beijing、cn-shanghai）

3.2 认证与签名（AK/SK） #

在火山引擎托管环境中，Lance REST 服务采用火山引擎标准的 AK/SK 签名鉴权机制。请求通常需要包含：

• Authorization: HMAC-SHA256 ...
• X-Date: YYYYMMDD'T'HHMMSS'Z'
• （可选）X-Expire: -1 | 0 | N（签名有效期控制）
• Region: {region}

签名算法与实现细节请参考官方文档：https://www.volcengine.com/docs/6369/67269

4. API 参考 #

4.1 公共说明 #

环境变量（示例）

export LANCE_HOST='https://{endpoint}'
export LANCE_BASE="${LANCE_HOST}/lance"
export REGION='cn-beijing'

通用 Header（生产建议）

通用 Query 参数

错误响应（示例）
失败时通常返回 application/json 的错误结构（字段名以实际返回为准）：

{
  "code": 404,
  "error": "Table not found",
  "type": "NoSuchTableException",
  "instance": "demo_catalog$demo_schema$demo_table",
  "detail": "..."
}

4.2 Namespace（命名空间）接口 #

4.2.1 列出子命名空间（catalog 列表）

• 方法：GET
• 路径：/lance/v1/namespace/{id}/list

输入参数

请求示例

curl --location "${LANCE_BASE}/v1/namespace/root/list" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

响应示例（200）

{
  "namespaces": ["demo_catalog", "demo_catalog2"],
  "page_token": null
}

4.2.2 创建命名空间

• 方法：POST
• 路径：/lance/v1/namespace/{id}/create

输入参数

请求示例：创建一级 namespace（catalog）

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog/create" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "create",
    "properties": {
      "comment": "created-by-demo"
    }
  }'

请求示例：创建二级 namespace（schema）

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/create" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "mode": "create",
    "properties": {
      "location": "tos://{bucket}/{prefix}/"
    }
  }'

响应示例（200）

{
  "properties": {
    "key": "value"
  }
}

4.2.3 描述命名空间

• 方法：POST
• 路径：/lance/v1/namespace/{id}/describe

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/describe" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

响应示例（200）

{
  "properties": {
    "location": "tos://{bucket}/{prefix}/"
  }
}

4.2.4 命名空间是否存在

• 方法：POST
• 路径：/lance/v1/namespace/{id}/exists

输入参数

响应

• 存在：200 OK（通常无响应体）
• 不存在：404 Not Found（返回错误结构）

4.2.5 删除命名空间

• 方法：POST
• 路径：/lance/v1/namespace/{id}/drop

注意：删除命名空间通常是递归的且不可恢复，建议先在测试环境验证。

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/drop" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{"mode":"FAIL","behavior":"RESTRICT"}'

响应示例（200）

{}

4.2.6 列出命名空间下的 tables

• 方法：GET
• 路径：/lance/v1/namespace/{id}/table/list

输入参数

请求示例

curl --location "${LANCE_BASE}/v1/namespace/demo_catalog%24demo_schema/table/list" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

响应示例（200）

{
  "tables": ["demo_catalog$demo_schema$demo_table"],
  "page_token": null
}

4.3 Table（表）接口 #

4.3.1 创建空表（只存元数据）

• 方法：POST
• 路径：/lance/v1/table/{id}/create-empty

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table0/create-empty" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "location": "tos://{bucket}/{prefix}/demo_table0.lance",
    "properties": {"k": "v"}
  }'

响应示例（200）

{
  "location": "tos://{bucket}/{prefix}/demo_table0.lance",
  "properties": {"key": "value"}
}

4.3.2 注册表（推荐：纳管已有数据目录）

• 方法：POST
• 路径：/lance/v1/table/{id}/register

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/register" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{
    "location": "tos://{bucket}/{prefix}/demo_table.lance",
    "mode": "CREATE",
    "properties": {
      "desc": "demo",
      "lance.hms.write-schema": true
    }
  }'

响应示例（200）

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {
    "location": "tos://{bucket}/{prefix}/demo_table.lance",
    "lance.register": "true",
    "desc": "demo"
  }
}

4.3.3 解注册表（仅删除元数据，不删除底层数据）

• 方法：POST
• 路径：/lance/v1/table/{id}/deregister

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/deregister" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

响应示例（200）

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

4.3.4 表是否存在

• 方法：POST
• 路径：/lance/v1/table/{id}/exists

输入参数

响应

• 存在：200 OK（通常无响应体）
• 不存在：404 Not Found（返回错误结构）

4.3.5 描述表

• 方法：POST
• 路径：/lance/v1/table/{id}/describe

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/describe" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}" \
  --header 'Content-Type: application/json' \
  --data '{}'

响应示例（200）

{
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

4.3.6 删除表

• 方法：POST
• 路径：/lance/v1/table/{id}/drop

注意：该操作可能删除元数据与底层数据文件，请务必确认影响范围。LAS Catalog 默认不删除实际数据。

输入参数

请求示例

curl --location --request POST "${LANCE_BASE}/v1/table/demo_catalog%24demo_schema%24demo_table/drop" \
  --header "Region: ${REGION}" \
  --header "X-Date: {ts}" \
  --header "Authorization: {auth}"

响应示例（200）

{
  "id": ["demo_catalog", "demo_schema", "demo_table"],
  "location": "tos://{bucket}/{prefix}/demo_table.lance",
  "properties": {"key": "value"}
}

5. 常见问题（FAQ） #

5.1 返回 401 / Unauthorized #

• 检查 Authorization/X-Date 是否按火山签名算法正确生成
• 检查 Region 是否与服务端 Region 一致
• 如使用了网关/反向代理，确保签名中 host 与实际请求 host 一致

5.2 创建成功但查询不到 #

• 检查 {id} 是否正确拼接与 URL 编码（尤其是 $、@、#）
• 检查是否访问了正确的 Endpoint 与路径前缀（是否需要额外的 /gravitino-lance）