API docs by Redocly

Resource Data (0.1.0)

Download OpenAPI specification:

Vega Backend Resource 数据子资源（/resources/{id}/data）相关 API。

本规范覆盖两类语义：

  1. 通用资源数据查询：POST /resources/{id}/data + X-HTTP-Method-Override: GET， 对任意 category 的 Resource 执行数据查询（filter + 分页）。
  2. dataset documents 的写/删/单条访问：PUT / GET single / DELETE 与 POST 的 Override: POST / Override: DELETE 分支，仅对 Resource.category=dataset 生效。

dataset 不顶层化：dataset 在系统中只是 Resource.category=dataset 的特化形态， 无独立 ID 体系。CRUD 走 /resources/{id}，仅 documents 子资源（即本规范）独立 API surface。

端点设计遵循 [vega-backend/CLAUDE.md] 的"端点设计规则"。POST /data 用 X-HTTP-Method-Override 头多分发，是为了兼容现有 query 语义并在同一条路径上 暴露 create / delete-by-filter，避免在仓库内引入新的"动作端点"形态。

错误码复用 Resource 系列：本规范不引入 Dataset.* 专属错误码；单条文档不存在 与 resource 不存在共用 VegaBackend.Resource.NotFound，靠 error_details 区分。

Resource 数据多分发端点

必须带 X-HTTP-Method-Override 头，值是 GET / POST / DELETE 之一 （大小写不敏感）；缺失或值非法返回 400 VegaBackend.InvalidParameter.OverrideMethod。

三种分支：

Override 行为 category 限制 body schema
GET 列表 / 查询文档 任意（兼容现有通用查询） ResourceDataQueryParams
POST 批量创建文档 dataset 强制 DocumentArray（每条 id 可选，无则后端生成）
DELETE 按 filter 删除文档 dataset 强制 ResourceDataQueryParams（filter_condition 必填非空）

Override: GET 响应：200 + { entries, total_count, paging }。cursor 模式通过 paging.next_cursor 续页；total_count 仅在 need_total=true 时返回。

Override: POST 响应：201 + { ids: [...] }。后端为无 id 的文档生成 id。

Override: DELETE 响应：204。空 filter_condition 拒绝 400 避免误删全表。

非 dataset category 的 resource 调 Override=POST/DELETE → 400 VegaBackend.Resource.InternalError.InvalidCategory。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

header Parameters
X-HTTP-Method-Override
required
string
Enum: "GET" "POST" "DELETE"

必填；值为 GET / POST / DELETE 之一

Request Body schema: application/json
required
One of
object

过滤条件，结构由 FilterCondCfg 决定。Override=DELETE 时必填且非空。

object (PagingRequest)

首次请求使用 offset 和 limit；cursor 续页以 cursor 定位，need_total 可携带但不会覆盖首次请求冻结值，其余查询参数不得重传。

Array of objects (SortField)

排序字段

output_fields
Array of strings

指定输出字段列表

need_total
boolean
Default: false

是否在响应里携带 total_count。cursor 首次请求的值会被冻结；续页携带的值被忽略。

object (Aggregation)
Array of objects (GroupByItem)
object (HavingClause)

Responses

Request samples

Content type
application/json
Example
{
  • "filter_condition": { },
  • "paging": {
    },
  • "sort": [
    ],
  • "output_fields": [
    ],
  • "need_total": false,
  • "aggregation": {
    },
  • "group_by": [
    ],
  • "having": {
    }
}

Response samples

Content type
application/json
{
  • "entries": [
    ],
  • "total_count": 0,
  • "paging": {
    },
  • "warnings": [
    ]
}

批量 update（upsert）文档

批量更新 dataset 文档，id 强制：body 数组中每条文档必须带 id 字段，缺失整批拒绝。

语义：upsert——id 存在则替换，不存在则按该 id 创建（service 层调 UpsertDocuments）。

category 限制：仅 dataset，否则 400 VegaBackend.Resource.InternalError.InvalidCategory。 空数组 body 拒绝 400 VegaBackend.InvalidParameter.RequestBody。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

Request Body schema: application/json
required
Array
id
string

文档 ID

property name*
additional property
any

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "ids": [
    ]
}

按 ids 批量删除 dataset 文档（best-effort）

批量删除 dataset 文档。best-effort 语义：

  • 缺失 id 静默跳过，不返回 404 / 4xx
  • 不接受 ignore_missing 选项

与 /build-tasks/{ids} / /discover-tasks/{ids} 的"整体事务 + ignore_missing" 不同；documents 场景的 missing 容忍度高，统一行为更简洁。

category 限制：仅 dataset。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

doc_ids
required
string

文档 ID 列表，逗号分隔（单条即长度 1 的退化情形）。 缺失 id 静默跳过；本端点不接受 ?ignore_missing 参数。

Responses

Response samples

Content type
application/json
{
  • "error_code": "string",
  • "description": "string",
  • "solution": "string",
  • "error_link": "string",
  • "error_details": null
}

获取单条文档

category 限制：仅 dataset。

文档不存在返回 404 VegaBackend.Resource.NotFound（与 resource 不存在共用同一 errcode；靠 error_details: "document {doc_id} not found" 区分）。

Resource 当前不可查询时返回 409，状态优先级和 errcode 与列表查询一致。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

doc_id
required
string

单个文档 ID

Responses

Response samples

Content type
application/json
{
  • "id": "string"
}

单条 update（upsert）文档

单条文档更新。doc_id 以 path 为准——body 不需要 id 字段，即使携带也以 path 覆盖（path 与 body id 不一致时仅记 warn log，不报错）。

语义同批量 PUT：upsert（id 存在则替换，不存在则按该 id 创建）。

category 限制：仅 dataset。

Authorizations:
OAuth2
path Parameters
id
required
string

Resource ID

doc_id
required
string

单个文档 ID

Request Body schema: application/json
required
id
string

文档 ID

property name*
additional property
any

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string"
}