JSON 查询 DSL 语法

本文档详细介绍 Foggy Dataset Model 的 JSON 查询 DSL（Domain Specific Language）完整语法。

1. 概述

JSON 查询 DSL 是一种声明式的查询语言，通过 JSON 格式描述查询条件、字段选择、分组、排序等操作。系统会将 DSL 解析并转换为 SQL 执行。

1.1 请求结构

{
    "page": 1,                          // 页码（从1开始）
    "pageSize": 20,                     // 每页条数
    "param": {
        "columns": [...],               // 查询列
        "slice": [...],                 // 过滤条件
        "groupBy": [...],               // 分组字段
        "orderBy": [...],               // 排序字段
        "calculatedFields": [...],      // 动态计算字段
        "returnTotal": true             // 是否返回汇总
    }
}

2. 字段引用格式

2.1 引用类型

2.2 嵌套维度引用

嵌套维度引用使用两种分隔符：. 负责维度层级导航，$ 负责属性访问。

{
    "columns": [
        "product$caption",                    // 一级维度
        "product.category$caption",           // 二级维度（.分隔层级）
        "product.category.group$caption"      // 三级维度
    ]
}

如果 TM 中定义了 alias，也可以使用别名引用：

{
    "columns": [
        "product$caption",                    // 一级维度
        "productCategory$caption",            // 二级维度（通过 alias）
        "categoryGroup$caption"               // 三级维度（通过 alias）
    ]
}

注意：不能用多个 $ 代替 .（如 product$category$caption），$ 只用于分隔维度和属性。

输出列名映射：路径中的 . 在响应数据中自动转为 _：

3. 过滤条件 (slice)

3.1 基本结构

{
    "field": "字段名",
    "op": "操作符",
    "value": "值",
    "maxDepth": 2           // 层级深度限制（仅层级操作符）
}

逻辑组合：使用 $or / $and 操作符组合多个条件：

{
    "$or": [条件1, 条件2, ...]    // 条件用 OR 连接
}
{
    "$and": [条件1, 条件2, ...]   // 条件用 AND 连接
}

3.2 操作符列表

3.2.1 比较操作符

= vs ===：= 在值为 null 时会自动转换为 IS NULL，而 === 始终生成 field = value，不做空值特殊处理。

3.2.2 集合操作符

3.2.3 模糊匹配操作符

3.2.4 空值操作符

isNullAndEmpty 生成 (field IS NULL OR field = '')，适用于需要同时判断 NULL 和空字符串的场景。

3.2.5 范围操作符

范围操作符示例：

{
    "param": {
        "slice": [
            {
                "field": "orderDate$caption",
                "op": "[)",
                "value": ["2024-01-01", "2024-07-01"]
            }
        ]
    }
}

生成的 SQL：

WHERE order_date >= '2024-01-01' AND order_date < '2024-07-01'

3.2.6 层级操作符（父子维度专用）

用于父子维度的层级查询，详见 父子维度文档。

向下查询（childrenOf/descendantsOf）通过 closure.parentKey = value 匹配，向上查询（ancestorsOf/selfAndAncestorsOf）通过 closure.childKey = value 匹配。

层级深度限制：

使用 maxDepth 参数限制查询的层级深度：

{
    "field": "team$id",
    "op": "descendantsOf",
    "value": "T001",
    "maxDepth": 2          // 只查询2层以内的后代
}

层级操作符示例：

{
    "param": {
        "columns": ["team$caption", "salesAmount"],
        "slice": [
            {
                "field": "team$id",
                "op": "childrenOf",
                "value": "T001"
            }
        ]
    }
}

生成的 SQL：

SELECT dim_team.caption, SUM(fact.sales_amount)
FROM fact_team_sales fact
LEFT JOIN team_closure closure ON fact.team_id = closure.child_id
LEFT JOIN dim_team ON closure.child_id = dim_team.id
WHERE closure.parent_id = 'T001'
  AND closure.distance = 1
GROUP BY dim_team.caption

3.2.7 向量操作符（向量模型专用）

用于向量模型的语义相似度检索，仅向量字段（type=VECTOR）支持。

similar 参数：

hybrid 参数：

向量搜索示例：

{
    "param": {
        "columns": ["docId", "title", "content", "_score"],
        "slice": [
            {
                "field": "embedding",
                "op": "similar",
                "value": {
                    "text": "销售业绩分析",
                    "topK": 10,
                    "minScore": 0.6
                }
            },
            { "field": "category", "op": "=", "value": "report" }
        ]
    }
}

混合搜索示例：

{
    "param": {
        "columns": ["docId", "title", "_score"],
        "slice": [
            {
                "field": "embedding",
                "op": "hybrid",
                "value": {
                    "text": "销售分析",
                    "keyword": "报告",
                    "topK": 10
                }
            }
        ]
    }
}

向量搜索结果按相似度降序排列，_score 字段表示相似度(0-1)。

3.3 逻辑组合 ($or / $and)

slice 数组中的条件默认使用 AND 连接。使用 $or 和 $and 操作符可以显式控制条件的逻辑组合。

3.3.1 $or 操作符

将多个条件用 OR 连接：

{
    "param": {
        "slice": [
            {
                "$or": [
                    { "field": "orderStatus", "op": "=", "value": "COMPLETED" },
                    { "field": "orderStatus", "op": "=", "value": "SHIPPED" }
                ]
            }
        ]
    }
}

生成的 SQL：

WHERE (order_status = 'COMPLETED' OR order_status = 'SHIPPED')

3.3.2 $and 操作符

将多个条件用 AND 连接（用于在 $or 内部显式分组）：

{
    "param": {
        "slice": [
            {
                "$or": [
                    { "field": "customer$customerType", "op": "=", "value": "VIP" },
                    {
                        "$and": [
                            { "field": "totalAmount", "op": ">=", "value": 1000 },
                            { "field": "orderCount", "op": ">=", "value": 5 }
                        ]
                    }
                ]
            }
        ]
    }
}

生成的 SQL：

WHERE (customer_type = 'VIP' OR (total_amount >= 1000 AND order_count >= 5))

3.3.3 混合使用

$or 和 $and 可以任意嵌套，实现复杂的条件组合：

{
    "param": {
        "slice": [
            { "field": "orderStatus", "op": "=", "value": "COMPLETED" },
            {
                "$or": [
                    { "field": "totalAmount", "op": ">=", "value": 1000 },
                    { "field": "customer$customerType", "op": "=", "value": "VIP" }
                ]
            }
        ]
    }
}

生成的 SQL：

WHERE order_status = 'COMPLETED'
  AND (total_amount >= 1000 OR customer_type = 'VIP')

3.4 等值条件简写

对于等值条件（op: "="），支持简写格式：

简写格式：当对象只有一个键值对，且键不是保留字时，自动解析为等值条件。

// 简写格式
{ "orderStatus": "COMPLETED" }

// 等价于完整格式
{ "field": "orderStatus", "op": "=", "value": "COMPLETED" }

混合使用示例：

{
    "slice": [
        { "orderStatus": "COMPLETED" },
        { "customer$customerType": "VIP" },
        { "field": "totalAmount", "op": ">=", "value": 1000 }
    ]
}

注意：保留字段名（field, op, value, $or, $and, $expr, maxDepth）不能作为简写格式的字段名。

3.5 HAVING 条件（聚合过滤）

当查询包含分组（groupBy）时，对聚合字段的过滤会自动识别并放入 HAVING 子句：

{
    "param": {
        "columns": ["customer$customerType", "SUM(totalAmount) AS totalSales"],
        "slice": [
            { "field": "orderStatus", "op": "=", "value": "COMPLETED" },
            { "field": "totalSales", "op": ">=", "value": 10000 }
        ],
        "groupBy": [
            { "field": "customer$customerType" }
        ]
    }
}

生成的 SQL：

SELECT customer_type, SUM(total_amount) AS totalSales
FROM fact_order
WHERE order_status = 'COMPLETED'
GROUP BY customer_type
HAVING SUM(total_amount) >= 10000

注意：$or 条件组中不能同时包含聚合字段和普通字段，因为无法在 WHERE 和 HAVING 间使用 OR。

3.6 字段间比较 ($field / $expr)

支持直接比较两个字段的值，无需创建计算字段。提供两种语法：

3.6.1 $field 引用

使用 {"$field": "字段名"} 作为 value，表示引用另一个字段而非字面值：

{
    "param": {
        "slice": [
            {
                "field": "salesAmount",
                "op": ">",
                "value": { "$field": "costAmount" }
            }
        ]
    }
}

生成的 SQL：

WHERE sales_amount > cost_amount

支持所有比较操作符：

3.6.2 $expr 表达式

使用 $expr 定义更复杂的字段间比较表达式：

{
    "param": {
        "slice": [
            { "$expr": "salesAmount > costAmount" }
        ]
    }
}

支持算术运算：

{
    "param": {
        "slice": [
            { "$expr": "salesAmount > costAmount * 1.2" },
            { "$expr": "profitAmount >= discountAmount + 100" }
        ]
    }
}

生成的 SQL：

WHERE (sales_amount > (cost_amount * 1.2))
  AND (profit_amount >= (discount_amount + 100))

3.6.3 与其他条件组合

$field 和 $expr 可以与普通条件和逻辑组合一起使用：

{
    "param": {
        "slice": [
            { "orderStatus": "COMPLETED" },
            { "field": "salesAmount", "op": ">", "value": { "$field": "costAmount" } },
            { "field": "quantity", "op": ">=", "value": 10 }
        ]
    }
}

在 $or 条件中使用：

{
    "param": {
        "slice": [
            {
                "$or": [
                    { "$expr": "salesAmount > costAmount * 1.5" },
                    { "field": "discountAmount", "op": ">", "value": 100 }
                ]
            }
        ]
    }
}

生成的 SQL：

WHERE ((sales_amount > (cost_amount * 1.5)) OR discount_amount > 100)

3.6.4 使用场景

4. 分组 (groupBy)

4.1 基本格式

完整格式：

{
    "param": {
        "groupBy": [
            { "field": "customer$customerType" },
            { "field": "orderDate$year" },
            { "field": "orderDate$month" }
        ]
    }
}

简写格式：对于只需指定字段名的分组，可使用字符串数组：

{
    "param": {
        "groupBy": ["customer$customerType", "orderDate$year", "orderDate$month"]
    }
}

混合使用：简写格式和完整格式可以混合：

{
    "param": {
        "groupBy": [
            "customer$customerType",
            { "field": "totalAmount", "agg": "AVG" }
        ]
    }
}

4.2 自定义聚合方式

可以在 groupBy 中覆盖默认的聚合方式：

{
    "param": {
        "groupBy": [
            { "field": "product$category" },
            { "field": "totalAmount", "agg": "AVG" }
        ]
    }
}

4.3 聚合类型

5. 排序 (orderBy)

5.1 基本格式

完整格式：

{
    "param": {
        "orderBy": [
            { "field": "totalAmount", "dir": "desc" },
            { "field": "orderId", "dir": "asc" }
        ]
    }
}

简写格式：支持多种字符串简写：

{
    "param": {
        "orderBy": ["-totalAmount", "orderId"]
    }
}

混合使用：

{
    "param": {
        "orderBy": [
            "-totalAmount",
            { "field": "orderId", "dir": "asc", "nullLast": true }
        ]
    }
}

5.2 参数说明

6. 动态计算字段 (calculatedFields)

允许在查询时定义计算字段，可在 columns、slice、groupBy、orderBy 中引用。

6.1 基本结构

{
    "param": {
        "calculatedFields": [
            {
                "name": "profitRate",
                "caption": "利润率",
                "expression": "profitAmount / salesAmount * 100",
                "agg": "SUM"
            }
        ],
        "columns": ["product$caption", "profitRate"]
    }
}

6.2 参数说明

6.3 支持的表达式

算术运算

• +, -, *, /, %

数学函数

• ABS(x) - 绝对值
• ROUND(x, n) - 四舍五入
• CEIL(x) / CEILING(x) - 向上取整
• FLOOR(x) - 向下取整
• MOD(x, y) - 取模
• POWER(x, y) / POW(x, y) - 幂运算
• SQRT(x) - 平方根
• SIGN(x) - 符号函数（正数返回1，负数返回-1，零返回0）
• TRUNCATE(x, n) / TRUNC(x, n) - 截断到指定小数位

日期函数

• YEAR(date) - 提取年份
• MONTH(date) - 提取月份
• DAY(date) - 提取日期
• HOUR(datetime) - 提取小时
• MINUTE(datetime) - 提取分钟
• SECOND(datetime) - 提取秒
• DATE(datetime) - 提取日期部分
• TIME(datetime) - 提取时间部分
• NOW() - 当前时间
• CURRENT_DATE() - 当前日期
• CURRENT_TIME() - 当前时间
• CURRENT_TIMESTAMP() - 当前时间戳
• DATE_ADD(date, interval) - 日期加法
• DATE_SUB(date, interval) - 日期减法
• DATEDIFF(date1, date2) - 日期差
• TIMESTAMPDIFF(unit, date1, date2) - 时间戳差值
• DATE_FORMAT(date, format) - 日期格式化
• STR_TO_DATE(str, format) - 字符串转日期
• EXTRACT(unit FROM date) - 提取日期部分

字符串函数

• CONCAT(s1, s2, ...) - 字符串连接
• CONCAT_WS(sep, s1, s2, ...) - 带分隔符的字符串连接
• SUBSTRING(s, start, len) / SUBSTR(s, start, len) - 截取子串
• LEFT(s, n) - 左截取 n 个字符
• RIGHT(s, n) - 右截取 n 个字符
• UPPER(s) - 转大写
• LOWER(s) - 转小写
• TRIM(s) - 去除两端空白
• LTRIM(s) - 去除左侧空白
• RTRIM(s) - 去除右侧空白
• LENGTH(s) - 字节长度
• CHAR_LENGTH(s) - 字符长度
• REPLACE(s, from, to) - 字符串替换
• INSTR(s, substr) - 查找子串位置
• LOCATE(substr, s) - 查找子串位置
• LPAD(s, len, pad) - 左侧填充
• RPAD(s, len, pad) - 右侧填充

条件与类型函数

• COALESCE(v1, v2, ...) - 返回第一个非空值
• NULLIF(v1, v2) - 如果相等返回 NULL
• IFNULL(v, default) / NVL(v, default) / ISNULL(v) - 空值处理
• IF(condition, trueVal, falseVal) - 条件判断
• CASE WHEN ... THEN ... ELSE ... END - 条件分支
• CAST(v AS type) / CONVERT(v, type) - 类型转换

窗口函数

窗口函数在计算字段中使用，需配合 partitionBy、windowOrderBy、windowFrame 参数：

窗口函数示例：

{
    "param": {
        "calculatedFields": [
            {
                "name": "salesRank",
                "caption": "销售排名",
                "expression": "RANK()",
                "partitionBy": ["region$caption"],
                "windowOrderBy": [{"field": "salesAmount", "dir": "desc"}]
            },
            {
                "name": "movingAvg",
                "caption": "7日移动平均",
                "expression": "AVG(salesAmount)",
                "partitionBy": ["product$id"],
                "windowOrderBy": [{"field": "salesDate$caption", "dir": "asc"}],
                "windowFrame": "ROWS BETWEEN 6 PRECEDING AND CURRENT ROW"
            },
            {
                "name": "prevDaySales",
                "caption": "前日销售额",
                "expression": "LAG(salesAmount, 1)",
                "partitionBy": ["product$id"],
                "windowOrderBy": [{"field": "salesDate$caption", "dir": "asc"}]
            }
        ],
        "columns": ["salesDate$caption", "product$caption", "salesAmount", "salesRank", "movingAvg", "prevDaySales"]
    }
}

注意：窗口函数不会触发 GROUP BY，它在每行数据上独立计算。

6.4 计算字段示例

{
    "param": {
        "calculatedFields": [
            {
                "name": "avgOrderAmount",
                "caption": "平均订单金额",
                "expression": "totalAmount / orderCount"
            },
            {
                "name": "salesGrowth",
                "caption": "销售增长率",
                "expression": "(currentSales - lastYearSales) / lastYearSales * 100"
            },
            {
                "name": "orderYear",
                "caption": "订单年份",
                "expression": "YEAR(orderDate)"
            }
        ],
        "columns": ["customer$caption", "avgOrderAmount", "salesGrowth"],
        "slice": [
            { "field": "salesGrowth", "op": ">", "value": 10 }
        ]
    }
}

7. 内联表达式

除了使用 calculatedFields 定义计算字段，还可以直接在 columns 中使用内联表达式。

7.1 语法格式

表达式 AS 别名

7.2 示例

{
    "param": {
        "columns": [
            "customer$caption",
            "YEAR(orderDate) AS orderYear",
            "SUM(totalAmount) AS totalSales",
            "totalAmount / quantity AS unitPrice"
        ],
        "groupBy": [
            { "field": "customer$caption" },
            { "field": "orderYear" }
        ]
    }
}

系统会自动将内联表达式转换为 calculatedFields，并识别聚合类型。

8. 分页参数

8.1 参数说明

8.2 示例

使用 page/pageSize：

{
    "page": 2,
    "pageSize": 20,
    "param": { ... }
}

使用 start/limit：

{
    "start": 20,
    "limit": 20,
    "param": { ... }
}

9. 响应结构

9.1 响应体

{
    "code": 0,
    "data": {
        "items": [
            {
                "orderId": "ORD001",
                "customer$caption": "客户A",
                "totalAmount": 1299.00
            }
        ],
        "total": 100,
        "totalData": {
            "total": 100,
            "totalAmount": 129900.00
        }
    },
    "msg": "success"
}

9.2 响应字段

9.3 totalData 说明

• 包含 columns 中指定的度量字段的聚合值
• 是对所有符合条件的数据进行聚合，不受分页影响
• 只有设置 returnTotal=true 时才返回

10. 完整示例

10.1 明细查询

POST /jdbc-model/query-model/v2/FactOrderQueryModel

{
    "page": 1,
    "pageSize": 20,
    "param": {
        "columns": [
            "orderId",
            "orderStatus",
            "orderTime",
            "customer$caption",
            "customer$customerType",
            "product$caption",
            "totalAmount"
        ],
        "slice": [
            { "field": "orderStatus", "op": "in", "value": ["COMPLETED", "SHIPPED"] },
            { "field": "orderTime", "op": "[)", "value": ["2024-01-01", "2024-07-01"] },
            { "field": "totalAmount", "op": ">=", "value": 100 }
        ],
        "orderBy": [
            { "field": "orderTime", "dir": "desc" }
        ],
        "returnTotal": true
    }
}

10.2 分组汇总查询

POST /jdbc-model/query-model/v2/FactOrderQueryModel

{
    "page": 1,
    "pageSize": 100,
    "param": {
        "columns": [
            "orderDate$year",
            "orderDate$month",
            "customer$customerType",
            "totalQuantity",
            "totalAmount"
        ],
        "slice": [
            { "field": "orderDate$caption", "op": "[)", "value": ["2024-01-01", "2024-07-01"] }
        ],
        "groupBy": [
            { "field": "orderDate$year" },
            { "field": "orderDate$month" },
            { "field": "customer$customerType" }
        ],
        "orderBy": [
            { "field": "orderDate$year", "dir": "desc" },
            { "field": "orderDate$month", "dir": "asc" }
        ]
    }
}

10.3 带计算字段的分析查询

POST /jdbc-model/query-model/v2/FactSalesQueryModel

{
    "page": 1,
    "pageSize": 50,
    "param": {
        "calculatedFields": [
            {
                "name": "profitRate",
                "caption": "利润率(%)",
                "expression": "profitAmount / salesAmount * 100"
            },
            {
                "name": "avgPrice",
                "caption": "平均单价",
                "expression": "salesAmount / salesQuantity"
            }
        ],
        "columns": [
            "product$category",
            "salesQuantity",
            "salesAmount",
            "profitAmount",
            "profitRate",
            "avgPrice"
        ],
        "slice": [
            { "field": "salesDate$caption", "op": "[)", "value": ["2024-01-01", "2024-07-01"] },
            { "field": "profitRate", "op": ">=", "value": 20 }
        ],
        "groupBy": [
            { "field": "product$category" }
        ],
        "orderBy": [
            { "field": "profitRate", "dir": "desc" }
        ]
    }
}

10.4 父子维度层级查询

POST /jdbc-model/query-model/v2/FactTeamSalesQueryModel

{
    "page": 1,
    "pageSize": 100,
    "param": {
        "columns": [
            "team$caption",
            "salesAmount"
        ],
        "slice": [
            {
                "field": "team$id",
                "op": "selfAndDescendantsOf",
                "value": "T001"
            }
        ],
        "groupBy": [
            { "field": "team$caption" }
        ],
        "orderBy": [
            { "field": "salesAmount", "dir": "desc" }
        ]
    }
}

10.5 复杂嵌套条件查询

POST /jdbc-model/query-model/v2/FactOrderQueryModel

{
    "page": 1,
    "pageSize": 20,
    "param": {
        "columns": [
            "orderId",
            "orderStatus",
            "customer$caption",
            "product$category",
            "totalAmount"
        ],
        "slice": [
            { "field": "orderTime", "op": "[)", "value": ["2024-01-01", "2024-07-01"] },
            {
                "$or": [
                    { "field": "customer$customerType", "op": "=", "value": "VIP" },
                    { "field": "totalAmount", "op": ">=", "value": 1000 }
                ]
            },
            { "field": "product$category", "op": "in", "value": ["数码电器", "家居用品"] }
        ],
        "orderBy": [
            { "field": "totalAmount", "dir": "desc" }
        ]
    }
}

生成的 SQL 条件：

WHERE order_time >= '2024-01-01' AND order_time < '2024-07-01'
  AND (customer_type = 'VIP' OR total_amount >= 1000)
  AND category IN ('数码电器', '家居用品')
ORDER BY total_amount DESC

10.6 HAVING 条件示例

POST /jdbc-model/query-model/v2/FactOrderQueryModel

{
    "page": 1,
    "pageSize": 50,
    "param": {
        "calculatedFields": [
            {
                "name": "orderCount",
                "expression": "COUNT(*)",
                "agg": "COUNT"
            },
            {
                "name": "totalSales",
                "expression": "SUM(totalAmount)",
                "agg": "SUM"
            }
        ],
        "columns": [
            "customer$customerType",
            "orderCount",
            "totalSales"
        ],
        "slice": [
            { "field": "orderStatus", "op": "=", "value": "COMPLETED" },
            { "field": "totalSales", "op": ">=", "value": 50000 },
            { "field": "orderCount", "op": ">=", "value": 10 }
        ],
        "groupBy": [
            { "field": "customer$customerType" }
        ],
        "orderBy": [
            { "field": "totalSales", "dir": "desc" }
        ]
    }
}

生成的 SQL：

SELECT customer_type, COUNT(*) AS orderCount, SUM(total_amount) AS totalSales
FROM fact_order
WHERE order_status = 'COMPLETED'
GROUP BY customer_type
HAVING SUM(total_amount) >= 50000 AND COUNT(*) >= 10
ORDER BY totalSales DESC

11. 错误处理

11.1 错误码

11.2 常见错误

字段不存在

{
    "code": 400,
    "msg": "未在查询模型FactOrderQueryModel中找到列: invalidField",
    "data": null
}

$or 条件混合聚合字段

{
    "code": 400,
    "msg": "$or 条件组中不能同时包含聚合字段(totalSales)和普通字段(orderStatus)",
    "data": null
}

12. 最佳实践

12.1 性能优化

• 只查询需要的字段，避免 columns: ["*"]
• 合理使用索引字段作为过滤条件
• 对于大数据量的分组汇总，考虑预聚合
• 单次查询建议不超过 1000 条

12.2 条件优化

• 优先使用等值条件（=、in）
• 范围条件尽量使用左闭右开 [) 格式
• 对于日期字段，推荐使用 $caption 进行过滤

12.3 安全性

• 字段访问受 QM 中 accesses 配置控制
• 敏感字段可通过 accesses 限制访问
• 所有条件参数都经过参数化处理，防止 SQL 注入

下一步

• TM 语法手册 - 表格模型定义
• QM 语法手册 - 查询模型定义
• 父子维度 - 层级结构维度
• 计算字段 - 计算字段详解
• DSL 查询 API - HTTP API 接口