• 简体中文

    • 指标（PredItemType）

    PredItemType 描述了一条返回列（指标或表达式），相当于 SQL SELECT 子句中的一项。其接口定义如下：

    export interface PredItemType {
  operator?: string;
  pred?: string | PredItemType;
  name?: string;
  schema?: string;
  query?: QueryType;
  args?: { [key: string]: any };
  params?: any[];        // 兼容旧版参数定义
  type?: string;         // @deprecated
  by?: string;           // @deprecated
}

    基本示例

    {
  "name": "销售额",
  "operator": "$sum",
  "pred": "amount"
}

    会被翻译为 SUM(amount) AS 销售额。其中：

    • name：结果中的列名；未设置时会自动生成。
    • operator：使用的算子（聚合、派生指标或自定义函数）。
    • pred：算子作用的字段，某些算子可嵌套新的 PredItemType。
    • query：该指标独有的过滤条件，不影响其他指标。
    • schema：当指标需要跨模型引用其他 schema 时显式指定。
    • args：算子的函数参数，推荐使用对象方式传递，而不是旧版的 params 数组。
    • params / type / by：兼容旧版的字段。新增写法建议统一收敛到 args。

    pred 也可以写成带下划线的跨表字段路径，例如 门店_地理位置_名称、物料_品牌_品类。这类路径的规则见 基础结构 中的“跨表字段路径”。

    常用算子

    算子说明
    $sum / $avg / $count常用聚合函数。$count 无需 pred。
    $distinct / $uniq统计去重后的数量，$uniq 针对用户 ID 等高并发场景做了优化。
    $yoy / $mom / $sply / $splm自动计算同比、环比或上一周期数值，并补齐时间对齐逻辑。
    $dailyavg / $monthlyavg将原始值按自然日 / 自然月平均，多用于平滑波动。
    $sql执行自定义 SQL 片段。可通过 args/params 注入变量。
    $piecewise将连续数值字段分段，常与用户画像等分桶场景配合使用。

    如需自定义指标，可在语义层中声明算子名称，然后在 operator 中引用该名称。

    嵌套 Pred

    pred 不一定只是一个字段名，也可以继续嵌套一个 PredItemType，用于表达函数组合。

    {
  "schema": "sales",
  "preds": [
    {
      "name": "销售额同比",
      "operator": "$yoy",
      "pred": {
        "name": "销售额",
        "operator": "$sum",
        "pred": "amount"
      }
    }
  ]
}

    这个例子表达的是“先求销售额汇总，再对该结果做同比计算”。在这类组合表达式中，外层 name 会成为最终结果列名，也会被 sort、having 等字段引用。

    算子参数（args）

    当算子需要额外参数时，使用 args 对象传递（推荐使用 args 而非 params）：

    {
  "preds": [
    {
      "name": "移动平均销售额",
      "operator": "$moving_avg",
      "pred": "amount",
      "args": {
        "window": 7,
        "center": true
      }
    }
  ]
}

    常用算子参数示例：

    算子可用参数说明
    $moving_avgwindow, center移动平均窗口大小和是否居中
    $percentilepercentile百分位数计算，如 0.5 表示中位数
    $sqlsql, bindings自定义 SQL 片段及变量绑定
    $piecewisecases分段规则配置

    对于 $avg 这类“按某些维度求均值”的场景，也优先使用 args.by 一类的对象参数，不再新增顶层 by。

    指标级别筛选

    同时计算“今年销售额”和“去年销售额”时，可以把时间条件写在各自的 query 字段中：

    {
  "schema": "sales",
  "preds": [
    {
      "name": "去年销售额",
      "operator": "$sum",
      "pred": "amount",
      "query": { "日期": { "year": 2023 } }
    },
    {
      "name": "今年销售额",
      "operator": "$sum",
      "pred": "amount",
      "query": { "日期": { "year": 2024 } }
    }
  ]
}

    分段算子（$piecewise）

    $piecewise 用于把连续数值字段映射成离散区间。直接编写 PredItemType 时，可以写成：

    {
  "preds": [
    {
      "name": "销售额段",
      "operator": "$piecewise",
      "pred": "销售额",
      "args": {
        "cases": [
          { "when": "amount < 1000", "then": "0-999" },
          { "when": "amount >= 1000 AND amount < 5000", "then": "1000-4999" },
          { "else": "5000+" }
        ]
      }
    }
  ]
}

    系统会将上述配置转译为 SQL CASE WHEN，并保证同一分段在不同看板中保持一致。若需要“按分段结果继续统计”，通常会由上层流程或执行器把分段结果再用于标准 groupby；GroupbyItemType 本身没有 operator 字段。

    更多算子约定可在语义层中查看，也可以通过插件扩展新的 operator。编写指标时请始终命名 name，确保 sort、having 等语义能够准确引用。

    跨 Schema 引用

    当需要引用其他模型（schema）的字段时，使用 schema 字段显式指定：

    {
  "schema": "orders",
  "preds": [
    {
      "name": "订单销售额",
      "operator": "$sum",
      "pred": "amount"
    },
    {
      "name": "关联客户数",
      "operator": "$count",
      "pred": "id",
      "schema": "customers"
    }
  ]
}

    系统会自动处理跨模型的关联逻辑，确保指标能够正确计算。当主 schema 和 pred 的 schema 不同时，执行引擎会根据语义层配置自动生成 JOIN。