VEGA 引擎 · 原生查询 API (0.1.0)

Vega Backend 原生查询端点（POST /resources/query）相关 API。

本端点执行经服务端校验和资源绑定的 SQL 或 DSL 原生查询：

• SQL 引擎（MariaDB/MySQL / PostgreSQL / SQL Server / Oracle / HANA / Doris）→ query 字段为 SQL 字符串
• 索引引擎（opensearch / elasticsearch）→ query 字段为 DSL JSON 对象

与 POST /resources/{id}/data（resource-data.yaml）的分工：

SQL 查询能力：执行单条顶层 SELECT，所有物理表通过受权限保护的 {{resource_id}} 占位符解析；DSL 的索引同样由 Resource 推导。支持同一 Catalog 内的 JOIN（含括号连接组）、WHERE、GROUP BY / HAVING、ORDER BY、LIMIT 和常用聚合函数 （COUNT、SUM、AVG、MIN、MAX）。

SQL 输入统一使用 MySQL SELECT 子集，通过 Go Parser → Builder 支持显式子查询、 JOIN（含括号连接组）、DISTINCT、分组、排序和 LIMIT/OFFSET， 并由 Resource/Catalog 对应的目标连接器生成源端 SQL 及绑定参数。

MariaDB/MySQL、PostgreSQL、HANA、Doris、Oracle 和 SQL Server 使用明确的只读内置函数名单，涵盖常用聚合、数值、 字符串和日期函数，并在访问连接器前校验参数数量及 DISTINCT / * 的组合。 OCTET_LENGTH 与 LENGTH 同义，返回字节长度；CHAR_LENGTH 返回字符长度。 PostgreSQL 将 IFNULL、LENGTH、日期取值和格式等映射为 PG 表达式； DATE_FORMAT/STR_TO_DATE 的格式使用字面量，支持 %Y/%y/%m/%d/%H/%h/%i/%s/%S/%f/%p/%x/%v/%%。 HANA 支持常用数值、字符串、日期函数和 HAVING 别名映射，CHAR 接受 ASCII 整数字面量 （0–127）及 NULL；DATE_FORMAT/STR_TO_DATE 的字面量格式支持 %Y/%y/%m/%d/%H/%h/%i/%s/%S/%f/%p/%% 和常用分隔符。 HANA 的 CHAR_LENGTH/SUBSTRING 使用 CESU-8 字符计数，LENGTH/OCTET_LENGTH 先编码为 UTF-8，再统计二进制字节。 PostgreSQL 和 HANA 的 SECOND 返回去除小数部分的整数秒。 Doris 使用原生函数映射及 BIGINT、LARGEINT、STRING/VARCHAR、DECIMAL 等目标类型；精确 DECIMAL 支持到 38 位。 Oracle 19c 使用命名参数和原生 NUMBER 绑定（最多 38 位有效数字），分页使用 OFFSET/FETCH。 空字符串按 Oracle 规则返回 null；LENGTH/OCTET_LENGTH 使用 LENGTHB，字节数取决于源库字符集。 CHAR 接受 0–127 的 ASCII 整数字面量及 NULL；DATE_FORMAT/STR_TO_DATE 支持 %Y/%m/%d/%H/%h/%i/%s/%S/%f/%p/%%；STR_TO_DATE 格式包含完整年月日，12 小时制配合 %p。 日期函数支持 ISO 日期/日期时间字符串字面量（空格或 T 分隔，最多六位小数秒），动态文本使用 STR_TO_DATE 显式转换。 NOW/CURRENT_TIMESTAMP 支持精度 0–6。 SQL Server 使用 @pN 命名参数，精确 DECIMAL 最多 38 位，LIMIT 0 生成 TOP (0)，其他分页使用 TOP 或 OFFSET/FETCH。 SQL 通道要求兼容级别至少 110；UTF-8 字节长度使用 SQL Server 2019+ 的 UTF-8 collation。 CHAR_LENGTH 保留尾随空格并按 Unicode 码点计数，CONCAT 保持 NULL 传播，除法/取模的零除数返回 NULL。 CHAR 接受 ASCII 整数字面量及 NULL；COUNT DISTINCT 只接受一个表达式。日期格式范围见 SQL Server 验收 README。 字段类型、隐式类型转换和分组合法性由目标数据库检查。 HANA 在只有 OFFSET、未设置 SQL LIMIT 时由方言生成器补充 LIMIT 2147384648；Doris 补充 LIMIT 9223372036854775807。

语法、函数调用或参数校验失败返回 HTTP 400 VegaBackend.Query.InvalidParameter。 通过 error_details 返回公共 Parser 的解析错误或目标连接器的能力错误。

Builder 通道对没有显式别名的计算表达式固定输出名称，避免参数占位符改变列名及子查询引用； 例如 SELECT 1,2 的输出列名为 1、2。重复输出名称仍需使用不同的显式别名。

MariaDB/MySQL、PG、HANA、Doris、Oracle 和 SQL Server 的 API 分页在不修改基础 Builder 的前提下组合 SQL 自带的 LIMIT/OFFSET； total_count 统计原始逻辑查询的结果行数。Builder cursor 只执行一次数据查询，在服务端保留 同一个 Rows 和连接，续页继续扫描，不重复执行 OFFSET 查询；额外预读一行判断是否有下一页。 每次续页重新校验资源权限和源端元数据版本；权限撤销或版本改变会关闭 cursor，版本改变返回 HTTP 409。读取超时、取消或结果集读取失败会终止 cursor，调用方应重新发起查询；读取前的 临时元数据服务错误可重试。首次 HTTP 请求结束不会关闭空闲 Rows，末页、显式关闭或空闲租约 到期会释放 Rows 与连接。need_total 的 COUNT 仍独立执行，不保证与数据查询共享同一快照或 NOW() 等时间函数的时间基准。

每个未读完的 Builder cursor 持有一个源端结果集和连接，应用的 keep_alive_sec 仅控制会话回收，不保证源库连接在租约内持续可用。大结果集在客户端暂停读取时可能使源端写入 阻塞；MariaDB/MySQL 可能触发 net_write_timeout。SELECT 尚未结束时持有的锁也可能使 DDL 等待。 应结合源端连接预算控制并发 cursor 数，读取完成后及时关闭，不再使用时调用 cursor 关闭接口。 源端超时或断连导致续页失败时，会话终止并释放资源，调用方需要重新发起查询。

MySQL/MariaDB 映射为 binary 的结果列（BIT、BINARY、VARBINARY 和各类 BLOB） 以原始字节的 base64 字符串返回，空字节串返回空字符串，NULL 保持 null。 BIT（包括 BIT(1)）不解释为 boolean；TINYINT 保留整数值，文本列仍返回文本。 PostgreSQL Builder 的 bytea 同样保留原始字节并以 base64 输出，NUMERIC 保留精确文本。

调用方仍应受 RBAC 与限流约束，底层账号必须保持只读。