Download OpenAPI specification:
Vega Backend Resource 数据子资源（/resources/{id}/data）相关 API。
large_integer 字段通过十进制字符串无损传输。Doris 源端比较、range、out_range、between、 分组、排序和 MIN/MAX 使用数值语义；SUM/AVG 暂不支持。 托管本地索引将其作为 string/keyword 存储和查询，复用既有字符串操作规则， 不支持 large_integer 数值范围或聚合语义；例如 "0100" 不匹配存储文本 "100"。 Dataset 不允许声明 large_integer 字段。 输入推荐使用整数字符串（可含正负号及前导零）；非法及越界常量遵循源端 CAST 设置。 区间不重排边界，range/between 为闭区间，out_range 为两端严格外部区间；NULL 边界拒绝。
本规范覆盖两类语义：
POST /resources/{id}/data + X-HTTP-Method-Override: GET，
对任意 category 的 Resource 执行数据查询（filter + 分页）。POST 的 Override: POST 创建一条文档，
PUT /resources/{id}/data 批量完整替换文档，单条 PUT 完整替换一条文档，GET / DELETE 支持按逗号分隔的文档 ID 批量操作；
它们以及 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 系列；条件删除部分完成使用
VegaBackend.Dataset.DeleteIncomplete。单条文档不存在
与 resource 不存在共用 VegaBackend.Resource.NotFound，靠 error_details 区分。
cursor 可通过 DELETE /resources/cursors/{cursor} 提前关闭，详见
raw-query.yaml。默认空闲租约为 1800 秒；单账号 cursor session
默认上限 100，全局默认上限 1000。
必须带 X-HTTP-Method-Override 头，值是 GET / POST / DELETE 之一
（大小写不敏感）；缺失或值非法返回 400 VegaBackend.InvalidParameter.OverrideMethod。
三种分支：
| Override | 行为 | category 限制 | body schema |
|---|---|---|---|
GET |
列表 / 查询文档 | 任意（兼容现有通用查询） | ResourceDataQueryParams |
POST |
创建一条文档 | dataset 强制 | Document（不得传 _id，由后端生成） |
DELETE |
按 filter 删除文档 | dataset 强制 | ResourceDataQueryParams（filter_condition 必填非空） |
Override: GET 响应：200 + { entries, total_count, paging }。cursor 模式通过
paging.next_cursor 续页；total_count 仅在 need_total=true 时返回。
逻辑视图查询要求 EE 专业版及以上授权；未安装 EE 扩展返回 501，
授权版本不足返回 403 Public.Forbidden。
HANA 源表无 SELECT 权限时返回 403
VegaBackend.Resource.SourceReadForbidden，不暴露驱动原始错误。
已保存的衍生逻辑视图因源字段删除、绑定/类型不匹配、输出 Feature 变化，
或固定过滤条件非法（包括缺值、非法范围、不支持的算子）、无法按当前 schema/index 配置构造时，
返回 400 VegaBackend.LogicalView.DefinitionInvalid。
description 包含可识别的相关字段及编辑视图的修复提示；error_details 包含
fields（源字段名数组；输出绑定使用 original_name，过滤条件使用 field 名称）及 reason
（source_field_mismatch、source_feature_mismatch、filter_field_missing 或 filter_incompatible）。
普通查询条件非法仍返回 400 查询参数错误；不因条件来自已保存定义而改为 500。
本地索引精确查询值超过 keyword ignore_above 时，返回 HTTP 400
VegaBackend.Resource.QueryValueExceedsKeywordLimit。metadata.field 为请求字段名，
metadata.limit 为正整数长度上限，单位为 UTF-16 code units。
客户端按 error_code 判断错误类型，使用 metadata 生成本地化提示，不解析 error_details。
此错误不会自动回源或降级为空结果；调用方可缩短值，或主动设置 ignore_local_index=true
（仅支持源查询的资源）。旧版后端的通用 InvalidParameter 错误仍按通用错误处理。
非过滤条件的视图存储结构损坏、源读取及模型服务故障仍按原有错误处理。
已保存的复合逻辑视图在首次查询和 cursor 续页时也暂时返回 501。
Override: POST 响应：201 + { id }。后端生成文档 ID；携带 _id 的 body 返回 400。
Override: DELETE 响应：成功默认返回 204；?return_result=true 时返回
200 和 DeleteByQueryResult。部分失败、版本冲突或超时返回 500
VegaBackend.Dataset.DeleteIncomplete，error_details 包含删除数量及失败结果。
失败时已删除的文档不会回滚，重试前应核验业务状态。
空 filter_condition 返回 400。
非 dataset category 的 resource 调 Override=POST/DELETE → 400
VegaBackend.Resource.InternalError.InvalidCategory。
| id required | string Resource ID |
| return_result | boolean Default: false 仅 Override=DELETE 生效；true 时成功返回 200 和实际结果，默认保持 204。 |
| X-HTTP-Method-Override required | string Enum: "GET" "POST" "DELETE" 必填；值为 GET / POST / DELETE 之一 |
object 过滤条件树。叶节点使用 field、operation、value 和 value_from（const/field）； and/or 通过 sub_conditions 嵌套。Override=DELETE 时必填且非空。 时间常量：date 为 YYYY-MM-DD；time 为 HH:mm:ss[.fraction]；
datetime 支持 RFC3339、YYYY-MM-DD HH:mm:ss[.fraction] 或 int64 整数毫秒时间戳
（JSON 整数或数字字符串）。小数秒支持 1–9 位；无时区 datetime 按服务器 TZ 解释，默认 UTC。
date/datetime 的 before 使用 可用操作取决于字段类型和查询通道。索引字段比较的日期族两侧均须为 date/datetime/timestamp。 索引 TEXT 的精确及模式匹配要求 keyword Feature。 本地索引常量 !=/not_eq 和 not_in 仅比较具有精确索引值的记录， NULL 或缺失字段不命中；约束位于各自的条件分支内，显式 OR null 仍按该分支求值。 对 string/text 使用 keyword 字段或子字段；原始字符串超过该字段 ignore_above 时， 原值仍保留在 _source，但不写入 keyword 索引和 doc_values，因此也不会命中上述否定条件， 即使查询常量本身未超限。平台新增 string/text keyword 特征的默认上限为 256， 长度单位为 UTF-16 code units，实际限制以索引 mapping 为准。 例如上限 256 时，300 个 ASCII 字符的 body 不会命中 body != "hello" 或 body not_in ["hello"]。这项限制可能使本地索引与源端 SQL 的结果不同； 显式 null/not_null/exist/not_exist 按各自字段的索引存在性求值， 不保证与上述比较条件覆盖全部原始值。 查询常量自身超限则返回 400 VegaBackend.Resource.QueryValueExceedsKeywordLimit， not_in 任一候选值超限也按此处理，与已存储长值不参与比较的行为不同。 日期类 not_in 的存在性约束也计入既有的 1024 条查询子句上限。 需要完整原始值比较时，对支持源查询的 table resource 可设置 ignore_local_index=true； 不会自动回源，dataset 没有原始表查询通道。正文检索可使用已配置全文特征的 match/match_phrase。 contain 在源查询中匹配逗号分隔值的全部给定项， 在索引查询中匹配任一项；索引 not_contain 排除全部给定项。 knn_vector 在索引维度已知时要求输入向量维度匹配。 非法输入或超限返回 HTTP 400，服务端配置或执行故障返回相应 5xx。 已保存的派生视图固定条件非法时返回 VegaBackend.LogicalView.DefinitionInvalid。 索引 datetime 集合最多 1024 个不同时刻；含范围条件的过滤树最多 1024 个查询子句； time 集合展开后最多 65536 项，并受引擎配置限制。 能力与兼容说明。 | |
object (PagingRequest) 首次请求使用 offset 和 limit；cursor 续页以 cursor 定位，need_total 可携带但不会覆盖首次请求冻结值，其余查询参数不得重传。 | |
Array of objects (SortField) 排序字段。派生逻辑视图的非聚合查询支持保留元字段 | |
| output_fields | Array of strings 指定输出字段列表。显式指定的字段必须全部合法；任一字段不存在时整单拒绝，返回
HTTP 400 |
| binary_mode | string Default: "metadata" Enum: "metadata" "content" Binary 字段的返回形式。省略时按 |
| ignore_local_index | boolean Default: false 是否跳过可用的本地索引并查询表的原始数据源；默认 |
| need_total | boolean Default: false 是否在响应里携带 total_count。cursor 首次请求的值会被冻结；续页携带的值被忽略。 |
object (Aggregation) | |
Array of objects (GroupByItem) 索引分组使用同一 PIT 的 composite 分页，保留 NULL/缺失键及多维 NULL 组合， 输出真正的 JSON null；空字符串、0、-1 和字符串 "NULL" 保持独立。 所有索引分组都要求源端支持 OpenSearch PIT 创建、搜索及关闭 API， 包括省略 aggregation，以及 count_distinct 默认或显式允许近似的查询。 PIT API 从 OpenSearch 2.4 引入，因此低于 2.4 的版本不支持此分组路径； 版本达到 2.4 仍须满足所用 API、参数和读取权限要求，不代表各版本均已验收。 当前不适配 Elasticsearch 的 /_pit API，不能因其支持 PIT 就视为兼容索引分组。 创建 PIT 时源端返回 400/404，转换为 HTTP 400 参数错误；401/403 转换为 源端读取权限错误。不回退到 terms 或自动切换查询通道。 日历分组仅返回存在文档的日期，不补齐缺口。COUNT/COUNT_DISTINCT 忽略空值， 已有分组内度量全为空时计数为 0，SUM/AVG/MIN/MAX 为 null。 SUM/MIN/MAX 的 Decimal 结果先按字段有效 scale 做 HALF_UP 归一化； 输出、HAVING、排序及分页使用同一个归一化值，AVG 保留既有结果精度。 HAVING 在聚合值归一化之后执行，再进行全局排序与 offset/limit 截取。 源库及索引未指定排序时按 group_by 顺序对分组键升序排序，NULL 在前； 显式排序并列时以尚未排序的分组键升序打破并列。索引路径由此替代旧 terms 的默认桶顺序。 每页 1000 桶，单页响应最多 8 MiB，保留分组状态计费预算 16 MiB， 整次执行最多 30 秒（更短请求超时优先），与精确去重共享每进程 4 个扫描槽位。 超预算返回 HTTP 422 VegaBackend.Query.ExecutionBudgetExceeded； 用户 limit 只截取完整计算后的结果，较小 limit 不减少扫描范围，也不绕过预算。 旧 terms 曾返回 top-N 的高基数查询，现在可能因完整扫描超预算而返回 422。 超时、分片失败或扫描不完整不返回部分结果。内部 composite 续页不开放公开聚合 cursor。 | |
object (HavingClause) |
{- "filter_condition": { },
- "paging": {
- "mode": "cursor",
- "offset": 0,
- "limit": 1,
- "keep_alive_sec": 60,
- "cursor": "string"
}, - "sort": [
- {
- "field": "string",
- "direction": "asc"
}
], - "output_fields": [
- "string"
], - "binary_mode": "metadata",
- "ignore_local_index": false,
- "need_total": false,
- "aggregation": {
- "property": "string",
- "aggr": "count",
- "allow_approximate": true,
- "alias": "string"
}, - "group_by": [
- {
- "property": "string",
- "description": "string",
- "calendar_interval": "minute"
}
], - "having": {
- "field": "__value",
- "operation": "==",
- "value": null
}
}{- "is_approximate": true,
- "query_source": "local_index",
- "entries": [
- {
- "_id": "string"
}
], - "total_count": 0,
- "paging": {
- "next_cursor": "string",
- "expires_at_sec": 0
}, - "warnings": [
- "string"
]
}仅支持 Dataset。按 entry 的 _id 创建或完整替换文档，未提供的旧字段不保留。
每次提交 1–1000 条，请求体不超过 32 MiB。
_id 必须是非空白的有效 UTF-8 字符串，最多 512 字节，同批不能重复。
ID 校验失败时整批返回 400；任一文档校验或向量生成失败时整批返回错误，不写入文档。
写入结果按输入顺序返回，可能部分成功，请逐条检查 status、error_code 和 retryable。
outcome_unknown 表示可能已经写入，重试前应核验结果，并避免旧数据覆盖新数据。
| id required | string Resource ID |
required | Array of objects [ 1 .. 1000 ] items |
{- "entries": [
- {
- "_id": "string"
}
]
}{- "entries": [
- {
- "id": "string",
- "status": 0,
- "error_code": "invalid_document",
- "retryable": true
}
]
}按请求 ID 顺序返回 { "entries": [...] }，单 ID 也使用同一响应结构。
默认严格：任一文档不存在即返回 404。?ignore_missing=true 时跳过缺失文档。
category 限制：仅 dataset。Resource 当前不可查询时返回 409，状态优先级和
列表查询一致。
| id required | string Resource ID |
| docid required | string 文档 ID 或以逗号分隔的文档 ID 列表。服务端会删除空白项并保留首次出现的 ID； 处理后没有 ID 时返回 400。PUT 仅接受单个文档 ID。 |
| ignore_missing | boolean Default: false 容忍缺失文档，跳过而非返回 404；默认 false |
{- "entries": [
- {
- "_id": "string"
}
]
}docid 是目标文档 ID。body 中的 _id 会被路径参数覆盖；文档已存在时完整替换，
不存在时以该 ID 创建，不支持 patch/merge 更新。
对 string / text 字段上的 vector Feature：若 body 显式携带派生字段
<field>_vector，服务端校验后直接使用；否则源文本非空时同步生成向量。生成或
校验失败时不会向 OpenSearch 写入该文档。
category 限制：仅 dataset。
| id required | string Resource ID |
| docid required | string 文档 ID 或以逗号分隔的文档 ID 列表。服务端会删除空白项并保留首次出现的 ID； 处理后没有 ID 时返回 400。PUT 仅接受单个文档 ID。 |
| _id | string 文档 ID |
| property name* additional property | any |
{- "_id": "string"
}{- "id": "string"
}默认严格：服务端在删除前核验全部文档，任一不存在即返回 404，且不发起删除。
?ignore_missing=true 时跳过不存在的文档，仅删除已找到的文档。
这是一请求内的预检语义；预检后发生的并发删除仍可能使底层批量删除失败。
category 限制：仅 dataset。
| id required | string Resource ID |
| docid required | string 文档 ID 或以逗号分隔的文档 ID 列表。服务端会删除空白项并保留首次出现的 ID； 处理后没有 ID 时返回 400。PUT 仅接受单个文档 ID。 |
| ignore_missing | boolean Default: false 容忍缺失文档，跳过而非返回 404；默认 false |
{- "error_code": "string",
- "description": "string",
- "error_details": null,
- "metadata": { }
}