API docs by Redocly

Raw Query (0.1.0)

Download OpenAPI specification:

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

本端点执行经服务端校验和资源绑定的原生查询，不做结构化 filter 解析：

  • SQL 引擎（mysql / postgresql / sqlserver / clickhouse / 达梦 / oracle）→ query 字段为 SQL 字符串
  • 索引引擎（opensearch / elasticsearch）→ query 字段为 DSL JSON 对象

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

维度 POST /resources/query POST /resources/{id}/data (Override:GET)
资源定位 SQL 使用受控 {{resource_id}} 占位符；DSL 使用顶层 resource_id 绑定 :id
输入 原生 SQL / DSL + format/dialect 结构化 filter_condition + 分页
输出 列元数据 + raw entries + cursor 分页 文档对象 + 可选 total_count + cursor 分页
Cursor paging.cursor / paging.next_cursor paging.cursor / paging.next_cursor
用途 同一 Catalog 内的复杂 SQL / DSL 应用层结构化访问

SQL 只读策略：SQL 只允许单条顶层 SELECT，且所有物理表必须由受权限保护的 Resource 占位符解析；DSL 的索引同样只能由 Resource 推导。当前可用的 SQL 子集为 同一 Catalog 内的 JOIN、WHERE、GROUP BY / HAVING、ORDER BY、LIMIT 和 常用聚合函数（COUNT、SUM、AVG、MIN、MAX）。子查询不被只读策略单独禁止； 窗口函数与其他内置函数须由 SQLGlot 识别为安全表达式，且由 input_dialect 和底层连接器支持。

不支持 WITH / CTE、UNION / INTERSECT / EXCEPT、多语句、SELECT INTO、 锁定读取，以及写入、DDL、事务、权限与过程类语句。函数仅允许 SQLGlot 可识别的具名 内置表达式：UDF 与未建模的方言函数一律被拒绝；文件读取、外部访问或休眠等高风险 内置函数（如 pg_read_file、http_get、sleep、system）另被显式拒绝。违反策略返回 HTTP 400 VegaBackend.Query.InvalidParameter，error_details 为 raw query rejected by read-only policy；请改写为单条顶层 SELECT。

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

执行原生查询（SQL 或 DSL）

请求体的 query 字段类型由 query_format 和 input_dialect 决定：

  • SQL：{"query":"SELECT * FROM {{resource_id}}", "query_format":"sql", "input_dialect":"postgres"}
  • SQL Server T-SQL：{"query":"SELECT TOP (20) * FROM {{resource_id}}", "query_format":"sql", "input_dialect":"tsql"}
  • OpenSearch DSL：{"query":{"resource_id":"...","query":{"match_all":{}}}, "query_format":"dsl", "input_dialect":"opensearch"}

实际执行连接器始终从 Resource/Catalog 推导，客户端不能通过输入方言选择数据源。 SQL Server Catalog 的目标方言固定为 tsql；客户端可直接提交 tsql，也可提交受支持的其它 SQL 输入方言，由服务端转换为 T-SQL。无论输入方言为何，EXEC、SELECT INTO、DDL/DML 和多语句 都会在访问数据库前被拒绝。由于 total-count 和部分分页查询需要使用 SQL Server 派生表，计算表达式 必须显式指定唯一列别名；通配符不能与其它投影列混用，多表 JOIN 的通配符必须指定表名（例如 orders.*）。

SQL 语法边界：只接受单条顶层 SELECT。支持同一 Catalog 内的 JOIN、 WHERE、GROUP BY / HAVING、ORDER BY、LIMIT 和常用聚合函数。子查询不被 只读策略单独禁止，但须由所选方言和连接器支持；窗口函数与其他内置函数还必须 由 SQLGlot 识别为安全表达式，UDF 与未建模的方言函数会被拒绝。WITH / CTE、 UNION / INTERSECT / EXCEPT、多语句、SELECT INTO、锁定读取、DML、DDL、 事务、权限和过程类语句均被拒绝。CTE 不可通过改写为 WITH 规避：请改为单条 顶层 SELECT，或拆分为多次查询。

OpenSearch DSL 使用 paging.mode: cursor 时必须提供非空 sort。客户端提交的 search_after 会被服务端忽略；该位置仅由服务端保存在不透明 cursor 中。排序应 包含稳定且唯一的 tiebreaker，避免相同排序值跨页重复或遗漏。

OpenSearch 聚合 DSL 仅支持 paging.mode: single，服务端强制 size: 0，并将 metric、terms/date_histogram 及其单链嵌套 bucket 展开为逐行 entries。不能 转换为行结构的聚合在访问 OpenSearch 前返回 400；paging.offset/limit 应用于 展开后的行结果，cursor 模式不支持聚合。

Authorizations:
OAuth2
Request Body schema: application/json
required
One of
required
string or object

查询语句。类型依赖 query_format：

  • SQL 引擎用字符串
  • 索引引擎（OpenSearch/Elasticsearch）用 JSON 对象
query_format
required
string
Enum: "sql" "dsl"

输入载体类型。

input_dialect
string
Enum: "postgres" "mysql" "trino" "duckdb" "tsql" "opensearch"

输入方言。SQL 省略时默认 postgres；SQL Server 原生 T-SQL 使用 tsql。 SQL Server Catalog 的执行目标方言始终是 tsql，必要时由服务端转换。DSL 必须是 opensearch。

object (PagingRequest)

SQL cursor 使用 OFFSET 分页；为避免底层数据变更导致跨页重复或遗漏，调用方应提供包含唯一 tiebreaker 的确定性 ORDER BY。服务端暂不强制校验该排序。

query_timeout_sec
integer <int64> [ 1 .. 3600 ]
Default: 60

单页查询超时（秒），仅首次请求可设置；cursor 续页沿用首次请求的值。[1, 3600]，默认 60。

need_total
boolean
Default: false

是否需要完整总数。仅为 true 时响应包含 total_count；cursor 首次请求的值会由服务端冻结并用于所有续页，续页携带的值不改变该行为。

Responses

Request samples

Content type
application/json
Example
{
  • "query": "string",
  • "query_format": "sql",
  • "input_dialect": "postgres",
  • "paging": {
    },
  • "query_timeout_sec": 60,
  • "need_total": false
}

Response samples

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