跳到主要内容

查询

网关前缀：${API_BASE}/data/query...

后端控制器：QueryController（/api/v1/query）。

请求体字段说明（QueryRequest）​

核心字段：

  • version：字符串，必填，版本号（当前使用 "1.0"）
  • from：字符串，必填，主实体名
  • as：字符串，可选，主实体别名
  • select：数组，可选，选择字段列表（每项 { expr, alias? }）
  • joins：数组，可选，按 relation 进行 join
    • using_relation：字符串，必填，关系名
    • as：字符串，可选，join 别名
    • join_type：inner | left | right | full（可选）
    • on_filter：Predicate，可选，附加 join 条件
    • select：string[]，可选，选择 join 表字段名列表
  • where：Predicate，可选，过滤谓词
  • group_by：string[]，可选，分组字段
  • having：Predicate，可选，分组后过滤
  • order_by：数组，可选，排序（每项 { field, direction?, nulls? }）
    • direction：asc | desc
    • nulls：first | last
  • limit：整数，可选
  • offset：整数，可选
  • time：对象，可选，时间配置（TimeConfig）
    • time_field：字符串，可选，时间字段名
    • time_range：对象，可选（start/end/preset）
      • start/end：字符串（时间字符串）
      • preset：last_7_days | last_30_days | last_60_days | last_90_days | last_180_days | this_month | last_month | this_year
    • grain：hour | day | week | month | quarter | year
    • timezone：字符串，可选
  • params：对象，可选，参数（供视图/模板化使用）
  • use_view：字符串，可选，使用视图
  • use_metrics：string[]，可选，使用指标（由服务端展开为查询表达式）

Predicate（通用过滤谓词）​

Predicate 采用统一结构（type 字段区分三类）：

  • 比较：type = "comparison"（或省略 type，默认 comparison）
    • field：字段名
    • op：eq | ne | gt | gte | lt | lte | in | not_in | like | ilike | between | is_null | is_not_null
    • value：任意类型（可为数组/字符串/数字/布尔）
  • 逻辑：type = "logical"
    • op：and | or
    • conditions：Predicate[]
  • 取反：type = "not"
    • op：not
    • condition：Predicate

示例（AND + OR）：

{
  "type": "logical",
  "op": "and",
  "conditions": [
    { "type": "comparison", "field": "status", "op": "eq", "value": "PAID" },
    {
      "type": "logical",
      "op": "or",
      "conditions": [
        { "type": "comparison", "field": "country", "op": "eq", "value": "US" },
        { "type": "comparison", "field": "country", "op": "eq", "value": "CA" }
      ]
    }
  ]
}

执行查询​

  • POST /query
  • 请求头：
    • Authorization: Bearer <token>
    • X-Tenant-Id: <tenantId>
  • 示例请求（join + where + 分页）：
curl -X POST \
  "${API_BASE}/data/query" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: tenant-abc123" \
  -d '{
    "version": "1.0",
    "from": "orders",
    "select": [
      { "expr": "id" },
      { "expr": "order_date" },
      { "expr": "total_amount", "alias": "amount" }
    ],
    "where": { "type": "comparison", "field": "status", "op": "eq", "value": "PAID" },
    "limit": 100,
    "offset": 0
  }'
  • 示例响应：
{"success": true, "data": {"status":"COMPLETED","data":[{"id":1,"order_date":"2024-09-01T00:00:00Z","amount":1200.5}],"totalRows":1}}

验证查询 DSL​

  • POST /query/validate
  • 权限：permitAll
  • 请求体：同 QueryRequest

解释查询计划​

  • POST /query/explain
  • 权限：admin / read
  • 请求头：X-Tenant-Id
  • 请求体：同 QueryRequest

常见错误示例​

  • 未知实体：
{"success": false, "message":"Entity 'unknown' not found", "errorCode":"QUERY_EXECUTION_FAILED"}
  • 非法字段：
{"success": false, "message":"Field 'amountx' not found in 'orders'", "errorCode":"QUERY_EXECUTION_FAILED"}
  • 非法时间范围：
{"success": false, "message":"from must be before to", "errorCode":"QUERY_EXECUTION_FAILED"}