VEGA 引擎 · 代理资源读取 API (0.1.0)

过滤条件树。叶节点使用 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 使用 [正整数间隔, 单位]，单位为 year/quarter/month/week/day/hour/minute/second/microsecond 中实际连接器支持的子集， PostgreSQL 还接受其已有的复数单位别名。间隔必须是 int64 范围内的正整数， 日期字符串、未知或空单位均返回 400，不再接受索引旧 [小时数, RFC3339 参考时刻] 格式。 索引支持 year/month/week/day/hour/minute/second，间隔数量上限为 2147483647， 还须满足实际索引字段的时间值域。date_nanos 的边界须位于 1970-01-01T00:00:00Z 至 2262-04-11T23:47:16.854775807Z； 普通 date 使用毫秒值域，不共用 date_nanos 的间隔限制。 超限时保存或执行均明确拒绝，返回 400 VegaBackend.Resource.QueryTimeOutOfRange， 不将条件截断或改写为空结果。索引 before 在服务器时区计算截止时刻， 年/月截断到目标月末，日/周使用 Go 标准库日历运算，小时/分钟按经过时间计算； 时区转换由标准库处理。值域校验和查询使用同一纳秒精度的绝对截止时刻。

可用操作取决于字段类型和查询通道。索引字段比较的日期族两侧均须为 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 项，并受引擎配置限制。 能力与兼容说明。

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

排序字段。派生逻辑视图的非聚合查询支持保留元字段 _score，无需在视图 Schema 中发布；索引通道按真实相关性分数排序，source 表查询忽略该项并保留其余排序项。 聚合查询中，__value 代表实际聚合结果列，即使 aggregation.alias 使用自定义名称。 省略 aggregation 且使用 HAVING count(*) 时，隐式计数输出同样为 __value，可用于排序。 索引分组仅支持按 group_by 字段、实际聚合结果别名或其 __value 引用排序。 对 Schema 中存在但不属于这些输出的普通字段排序，返回 HTTP 400 参数错误， 不再像旧 terms 分组路径一样静默忽略；即使该字段是聚合输入，也不能据此排序。 分组查询保留用户指定的排序优先级和方向，再按 group_by 顺序追加尚未排序的分组键升序， 以保证并列结果在 offset/limit 分页时具有确定顺序；未指定排序时按全部分组键升序。 分组查询的显式排序统一为升序 NULL 在前、降序 NULL 在后；PostgreSQL 源库 与索引路径采用相同规则。普通明细查询保留各连接器已有的 NULL 排序语义。

指定输出字段列表。显式指定的字段必须全部合法；任一字段不存在时整单拒绝，返回 HTTP 400 VegaBackend.Query.InvalidParameter.OutputField，不静默删除字段。 字段存在但当前查询通道不支持读取时返回 HTTP 400 VegaBackend.Query.UnsupportedOutputField；默认投影没有可查询字段时返回 HTTP 400 VegaBackend.Query.NoQueryableFields。真实源连接、执行故障不归入这些错误。 省略或传空列表使用默认投影。本地索引通道对 Binary/Other 字段保留 unavailable 展示语义，显式请求与默认投影一致；该占位表示索引中无法读取原值。 聚合查询只能指定分组字段和实际聚合结果别名（未指定 alias 时为 __value）； 其他源字段不能作为聚合输出。显式选择仅裁剪结果列，不改变分组、排序、分页、行数或 total。 派生逻辑视图的非聚合查询可指定 _score；索引通道返回真实 相关性分数，source 表查询不返回该元字段，不补零或伪造分数。

Binary 字段的返回形式。省略时按 metadata 处理并返回字节长度；content 返回 Base64 编码内容与字节长度。cursor 续页不得重复传递。

是否跳过可用的本地索引并查询表的原始数据源；默认 false。仅对 table resource 生效。cursor 续页不得重复传递。

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

索引分组使用同一 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。