计算字段

计算字段允许在查询时动态定义新的列，通过表达式计算得到值，无需修改 TM/QM 模型。

1. 概述

计算字段有两种定义方式：

1. calculatedFields 参数：在 DSL 请求中定义
2. 内联表达式：在 columns 中直接写 expression as alias

2. 通过 calculatedFields 定义

2.1 基本格式

{
    "param": {
        "calculatedFields": [
            {
                "name": "netAmount",
                "caption": "净销售额",
                "expression": "salesAmount - discountAmount"
            }
        ],
        "columns": ["orderId", "salesAmount", "discountAmount", "netAmount"]
    }
}

2.2 字段说明

2.3 表达式中的列引用

表达式可以引用：

• 模型中的属性名
• 模型中的度量名
• 维度列：dimension$caption, dimension$id, dimension$property
• 其他计算字段名（需在当前字段之前定义）

3. 通过内联表达式定义

在 columns 中直接使用 expression as alias 格式：

{
    "param": {
        "columns": [
            "orderId",
            "salesAmount",
            "salesAmount * 1.1 as adjustedAmount",
            "ROUND(salesAmount, 2) as roundedAmount"
        ]
    }
}

3.1 聚合表达式

{
    "param": {
        "columns": [
            "product$categoryName",
            "sum(salesAmount) as totalSales",
            "count(*) as orderCount"
        ],
        "groupBy": [
            { "field": "product$categoryName" }
        ]
    }
}

注意：内联表达式的别名不能与模型中已有的字段名相同，否则会报错。

4. 支持的表达式

4.1 算术运算

复合表达式：

(salesAmount - discountAmount) * 1.13

4.2 数学函数

4.3 日期函数

4.4 字符串函数

4.5 空值处理函数

4.6 聚合函数

5. 条件聚合写法

当需要表达“条件计数 / 条件求和 / 条件均值”时，不新增 count_if / sum_if / avg_if 语法糖，统一使用现有聚合函数包裹 IF(...)：

SUM(IF(cond, 1, 0))
SUM(IF(cond, amount, 0))
AVG(IF(cond, amount, NULL))
COUNT(IF(cond, 1, NULL))

5.1 运算符与多个条件

• 条件表达式继续使用现有 DSL 比较与逻辑运算符
• 相等判断使用 ==
• 多个条件可用 && / ||

示例：

IF(stage$caption == 'Won', 1, 0)
IF(state == 'sale' && amountTotal > 100, amountTotal, 0)

5.2 推荐写法

{
    "param": {
        "columns": [
            "salesTeam$caption",
            "sum(if(stage$caption == 'Won', 1, 0)) as wonCount",
            "sum(if(state == 'sale', amountTotal, 0)) as confirmedAmount",
            "avg(if(stage$caption == 'Won', amountTotal, null)) as avgWonAmount",
            "count(if(stage$caption == 'Won', 1, null)) as wonOrderCount"
        ],
        "groupBy": [
            { "field": "salesTeam$caption" }
        ]
    }
}

5.3 SQL 降级规则

JDBC 引擎不会依赖数据库原生 IF(...)。表达式在 SQL 生成时会统一降级为标准 SQL：

SUM(CASE WHEN stage_caption = 'Won' THEN 1 ELSE 0 END)
SUM(CASE WHEN state = 'sale' THEN amount_total ELSE 0 END)
AVG(CASE WHEN stage_caption = 'Won' THEN amount_total ELSE NULL END)
COUNT(CASE WHEN stage_caption = 'Won' THEN 1 ELSE NULL END)

5.4 使用边界

• if(...) 中的相等判断使用 ==，不要写 SQL 风格的 =
• AVG(IF(...)) 若希望只统计命中条件的样本，else 分支应写 null，不要写 0
• COUNT(IF(...)) 若希望只统计命中条件的行，推荐写 COUNT(IF(cond, 1, null))
• 当前对外暴露仍然是 if(...)，内部会在编译阶段归一化为 IIF(...) 再继续处理

6. 完整示例

6.1 简单算术表达式

{
    "param": {
        "calculatedFields": [
            {
                "name": "netAmount",
                "caption": "净销售额",
                "expression": "salesAmount - discountAmount"
            }
        ],
        "columns": ["orderId", "salesAmount", "discountAmount", "netAmount"]
    }
}

生成的 SQL：

SELECT
    order_id AS orderId,
    sales_amount AS salesAmount,
    discount_amount AS discountAmount,
    (sales_amount - discount_amount) AS netAmount
FROM fact_sales

6.2 利润率计算

{
    "param": {
        "calculatedFields": [
            {
                "name": "profitRate",
                "caption": "利润率(%)",
                "expression": "profitAmount * 100.0 / salesAmount"
            }
        ],
        "columns": ["orderId", "salesAmount", "profitAmount", "profitRate"],
        "slice": [
            { "field": "salesAmount", "op": ">", "value": 0 }
        ]
    }
}

6.3 链式计算字段

计算字段可以引用其他计算字段：

{
    "param": {
        "calculatedFields": [
            {
                "name": "netAmount",
                "caption": "净销售额",
                "expression": "salesAmount - discountAmount"
            },
            {
                "name": "taxIncluded",
                "caption": "含税金额",
                "expression": "netAmount * 1.13"
            }
        ],
        "columns": ["orderId", "salesAmount", "netAmount", "taxIncluded"]
    }
}

6.4 引用维度列

{
    "param": {
        "calculatedFields": [
            {
                "name": "yearMonth",
                "caption": "年月",
                "expression": "CONCAT(YEAR(salesDate$caption), '-', MONTH(salesDate$caption))"
            }
        ],
        "columns": ["orderId", "salesDate$caption", "yearMonth", "salesAmount"]
    }
}

6.5 计算字段作为过滤条件

{
    "param": {
        "calculatedFields": [
            {
                "name": "profitRate",
                "caption": "利润率",
                "expression": "profitAmount * 100.0 / salesAmount"
            }
        ],
        "columns": ["orderId", "salesAmount", "profitAmount", "profitRate"],
        "slice": [
            { "field": "salesAmount", "op": ">", "value": 0 },
            { "field": "profitRate", "op": ">", "value": 10 }
        ]
    }
}

6.6 分组汇总中的计算字段

{
    "param": {
        "columns": [
            "product$categoryName",
            "sum(salesAmount) as totalSales",
            "sum(profitAmount) as totalProfit",
            "sum(profitAmount) * 100.0 / sum(salesAmount) as profitRate"
        ],
        "groupBy": [
            { "field": "product$categoryName" }
        ],
        "orderBy": [
            { "field": "totalSales", "order": "desc" }
        ]
    }
}

7. 安全性

7.1 禁止的函数

以下函数会被拦截并抛出 SecurityException：

• EXEC、EXECUTE
• DROP、DELETE、UPDATE、INSERT
• CREATE、ALTER、TRUNCATE
• 其他未在白名单中的函数

7.2 错误处理

8. 最佳实践

1. 避免除零错误：除法运算前添加 salesAmount > 0 条件
2. 使用 COALESCE：处理可能为 NULL 的字段
3. 命名规范：计算字段使用有意义的名称，避免与已有字段冲突
4. 链式依赖：被引用的计算字段需在引用者之前定义
5. 性能考虑：复杂的计算字段可能影响查询性能

下一步

• JSON 查询 DSL - 查询 DSL 完整语法（推荐阅读）
• 查询 API - HTTP API 接口
• TM 语法手册 - 表格模型定义
• QM 语法手册 - 查询模型定义