Lance 表维护

API 总览

Lance 表维护（Lance table maintenance）共提供 8 个对外 HTTP API：5 个异步任务提交接口，3 个任务查询、列举和删除接口。

访问地址与表标识

全部接口必须通过 Table Bucket 三级域名访问；请求中的 {tableBucketHost} 使用目标 Table Bucket 对应的域名。服务端从 Host 获取 Table Bucket 身份，URI 不携带 Table Bucket ARN。

接口前缀是 /lance/oss/v1，与普通 Lance 表管理接口的 /lance/v1 前缀不同。

服务端处理 id 时，先做 URL Decode，再按 delimiter 拆分，必须恰好得到非空的命名空间和表名两段。仅支持一级命名空间（如 prod），不支持多级（如 a.b）。表名沿用 Lance 表管理接口的校验规则；命名空间允许的字符集取决于 Table Bucket 类型。

自定义 delimiter 不能包含 /、:、-，支持多个字符。示例：

POST /lance/oss/v1/table/prod__documents/compact?delimiter=__ HTTP/1.1
Host: {tableBucketHost}
Date: GMT Date
Authorization: SignatureValue
Content-Type: application/json

所有操作都会校验表存在、调用权限以及表格式为 LANCE。任务以真实 Table ARN 隔离；删除后重建的同名表不能通过名称读取旧表任务。

请求与响应头

SignatureValue 是签名占位符，实际请求应由客户端按已配置的 OSS/Table 签名方式生成。

Host: {tableBucketHost}
Date: GMT Date
Authorization: SignatureValue
Content-Type: application/json

Body 使用 JSON。非空 Body 的请求建议提供 Content-MD5；提供时服务端会校验与 Body 的一致性。

8 个接口的成功响应均设置：

x-oss-table-id: {table_id}

此处的 table_id 是服务端表元数据中的真实 ID，与 URI 中的 namespace$table_name 不同。JSON 成功响应的 Content-Type 为 application/json；Delete 成功响应没有 Body。

权限

服务端使用查表得到的真实 Table ARN，结合 RAM、Table Bucket Policy 和 Table Policy 完成鉴权。本组接口复用已有维护类 Action。

异步提交、参数保存与任务额度

• Submit 成功返回 HTTP 200，表示任务已经持久化，初始 status 为 submitted；不表示维护操作执行完成。

• 每次 POST 都创建新的任务 ID。当前没有客户端请求去重或 Idempotency-Key 语义；重复提交可能创建多个任务。

• 服务端将已识别参数补齐默认值后写入任务 params。未知 JSON 字段通常被忽略，不会自动成为任务参数；例如已移除的 Compact batch_size。

• 提交时仅校验请求格式和基础参数；列或索引是否存在、参数组合能否实际执行等，在任务执行时才检查。因此提交成功的任务仍可能进入 failed 状态。

• 当前默认每个 Table ARN + task_type 最多保留 1000 条任务（包含 submitted、running、completed、failed）。终态（任务状态为completed、failed）不会自动释放额度，需要通过DeleteLanceTask删除记录后释放。达到额度返回 429 / TaskQuotaExceeded / 10002，客户端应捕获并重试。额度限制为尽力保证，高并发下可能短暂超出上限，不应在客户端依赖此上限做断言。

任务状态

状态流转：submitted → running → completed；submitted 与 running 可直接转为 failed。终态（completed、failed）不可回退。Get/List会原样透传存储中出现的未知状态，以兼容后续扩展，未知状态仍计入额度；当前仅支持删除 completed 和 failed 两个终态。

任务执行失败和查询失败是两种情况：如果 GetLanceTaskStatus 成功读到一条失败任务，HTTP 仍返回 200，任务对象中status="failed"且error非空；只有查询请求本身失败（如任务不存在、参数非法）才使用下述顶层错误结构。

错误响应格式

本组接口使用 Lance 的统一 JSON 错误格式：

{
  "error": "TaskNotFound",
  "code": 10000,
  "detail": "The specified Lance maintenance task does not exist.",
  "instance": "{request_id}"
}

detail 为示例文本，以实际服务端返回为准。

还可能返回通用 OSS 请求校验错误。错误数字优先根据 error 精确映射，不应仅根据 HTTP 状态码推算。

接入顺序示例

1. 对 prod$documents 调用一个 Submit API，记录响应 task_id。

2. 使用同一 Table Bucket、同一表调用 GetLanceTaskStatus，读取 task_info.status。

3. 需要查看历史任务时，按完整 task_type 调用ListLanceTasks，并将响应返回的 next_marker 作为下次请求的marker循环翻页，直至next_marker为空。

4. 对completed / failed 任务读取并保存需要的结果后调用 DeleteLanceTask API，释放任务记录额度。