Download OpenAPI specification:
Vega Backend 构建任务(BuildTask)相关 API。
BuildTask 是顶级独立资源,每条 task 关联 1 个 Resource,对其执行 streaming / batch 两种模式之一的构建。状态机:
pending → running → stopping → stopped ↘ completed ↘ failed ↘ cancelled
外部仅可触发 start / stop 两个动作;其它状态由 worker 内部转移,外部只读。
start / stop 返回 HTTP 202 且 body 为空,仅表示"指令被接受",不表示
status 已切换;持久化 status 由 worker 实际执行时写入,客户端如需感知应轮询 GET。
端点设计遵循 [vega-backend/CLAUDE.md] 的"端点设计规则":批量删除走 path
(DELETE /build-tasks/{ids},逗号分隔),不提供 /resources/{id}/build-tasks
嵌套列表视图——按父资源过滤一律走 GET /build-tasks?resource_id={id}。
分页获取构建任务;支持按 resource_id / catalog_id / status / mode 过滤。
| resource_id | string 按归属 resource 过滤 |
| catalog_id | string 按归属 catalog 过滤 |
| status | Array of strings Items Enum: "pending" "running" "stopping" "stopped" "completed" "failed" "cancelled" 按状态过滤;多个状态重复传递该参数,状态之间为 OR 关系。 |
| mode | string Enum: "streaming" "batch" 按任务模式过滤 |
| offset | integer <int64> >= 0 Default: 0 分页偏移量,>=0,默认 0 |
| limit | integer <int64> Default: 20 每页数量,默认 20 |
| sort | string Default: "create_time" Enum: "create_time" "start_time" "finish_time" "last_progress_time" 排序字段,默认按创建时间排序 |
| direction | string Default: "desc" Enum: "asc" "desc" 排序方向,默认 desc |
{- "entries": [
- {
- "id": "string",
- "resource_id": "string",
- "resource_name": "string",
- "catalog_id": "string",
- "catalog_name": "string",
- "status": "string",
- "mode": "string",
- "execute_type": "string",
- "total_count": 0,
- "synced_count": 0,
- "synced_mark": "string",
- "error_msg": "string",
- "creator": {
- "id": "string",
- "type": "string",
- "name": "string"
}, - "create_time": 0,
- "start_time": 0,
- "finish_time": 0,
- "last_progress_time": 0
}
], - "total_count": 0
}为指定 Resource 创建构建任务。同一 Resource 同时只能有一个 BuildTask;
已存在时返回 400 VegaBackend.BuildTask.Exist。
streaming 模式要求 Resource 在 source_metadata.primary_keys 中声明主键。batch 模式要求 build_key_fields 非空。pending。| resource_id required | string 关联 Resource ID(必填) |
| mode required | string Enum: "streaming" "batch" 任务模式 |
| execute_type | string Enum: "incremental" "full" batch 执行类型;省略时服务端默认 |
{- "resource_id": "string",
- "mode": "streaming",
- "execute_type": "incremental"
}{- "id": "string"
}| id required | string BuildTask ID;DELETE 时可传逗号分隔的 ID 列表 |
{- "id": "string",
- "resource_id": "string",
- "catalog_id": "string",
- "resource_name": "string",
- "catalog_name": "string",
- "status": "pending",
- "mode": "streaming",
- "execute_type": "incremental",
- "total_count": 0,
- "synced_count": 0,
- "synced_mark": "string",
- "error_msg": "string",
- "creator": {
- "id": "string",
- "type": "string",
- "name": "string"
}, - "create_time": 0,
- "start_time": 0,
- "finish_time": 0,
- "last_progress_time": 0,
- "failure_detail": "string",
- "index_config": {
- "build_key_fields": [
- "string"
], - "features": {
- "property1": {
- "vector": {
- "model_id": "string",
- "model_name": "string",
- "model_type": "string",
- "embedding_dim": 0,
- "batch_size": 0,
- "max_tokens": 0
}, - "fulltext": {
- "analyzer": "string"
}
}, - "property2": {
- "vector": {
- "model_id": "string",
- "model_name": "string",
- "model_type": "string",
- "embedding_dim": 0,
- "batch_size": 0,
- "max_tokens": 0
}, - "fulltext": {
- "analyzer": "string"
}
}
}
}
}整体事务语义:所有 id 通过预校验后才进入删除阶段,任一预校验失败整批不删。
预校验顺序:
running / stopping → 409 VegaBackend.BuildTask.HasRunningExecution,
error_details 携带 { running_ids: [...] }。状态拦截不可绕过,必须先 stop 再删。ignore_missing)→ 404 VegaBackend.BuildTask.NotFound,
error_details 携带 { missing_ids: [...] }。| id required | string BuildTask ID;DELETE 时可传逗号分隔的 ID 列表 |
| ignore_missing | boolean Default: false 放宽不存在性检查:缺失 id 视为已删除(静默跳过),其它 id 正常删。 不影响 running/stopping 拦截。 |
| delete_active_index | boolean Default: false 是否删除当前活跃索引;默认 |
{- "error_code": "string",
- "description": "string",
- "solution": "string",
- "error_link": "string",
- "error_details": null
}合法状态转移:status ∈ {stopped, failed} → pending → running。
failed 允许重试;pending 已在队列中、completed 已结束,二者均不允许 start。
batch 任务默认按 synced_mark 续跑;incremental 任务始终
保持增量续跑,reset 对它无效。full 任务仅在 reset=true 时清除进度并从头重建,
不修改原始 execute_type;
worker 实际开始执行时会清空 error_msg。
响应 status 滞后:HTTP 202 表示"启动指令已被接受并入队",不表示
status 已切换为 running。worker 实际执行时才会写为 running,
客户端如需确认应轮询 GET。响应 body 为空。
非幂等:对非 stopped / failed 状态的 task 调用 start 返回 409
VegaBackend.BuildTask.InvalidStateTransition。
| id required | string BuildTask ID |
| reset | boolean Default: false 仅对原始 |
{- "reset": false
}{- "error_code": "string",
- "description": "string",
- "solution": "string",
- "error_link": "string",
- "error_details": null
}合法状态转移:
pending → stopped:任务尚在队列中,直接标记停止,worker 出队后会跳过。running → stopping:正常停止,worker 在批间检查点退出后写 stopped。响应 status 滞后:HTTP 202 表示"停止指令已被记录"。running 任务的
stopping → stopped 由 worker 异步推进,客户端可轮询 GET 拿最新 status。响应 body 为空。
非幂等:对非 pending / running 状态的 task 调 stop 返回 409;
stopping 中再次 stop 也返回 409
VegaBackend.BuildTask.InvalidStateTransition。
| id required | string BuildTask ID |
{- "error_code": "string",
- "description": "string",
- "solution": "string",
- "error_link": "string",
- "error_details": null
}