• 简体中文

    • Logicform 基础结构

    Logicform 采用 JSON 结构描述一条查询请求。接口定义可在 semanticdb-core/src/logicform/logicform.ts 中找到，核心内容如下：

    export interface LogicformType {
  schema: string;
  query?: QueryType;
  preds?: PredItemType[];
  groupby?: GroupbyItemType[];
  sort?: { [key: string]: 1 | -1 };
  having?: QueryType;
  limit?: number;
  limitBy?: number;
  skip?: number;
  representation?: RepresentationType;
  entity_id?: string;
}

    其中 PredItemType、GroupbyItemType、QueryType 等结构都会在后续章节单独说明。

    字段与 SQL 的对应

    字段必填说明SQL 对应
    schema是业务建模阶段配置的模型或实体，决定 FROM 表及权限范围。FROM table
    preds否需要返回的指标或表达式，通常包含聚合函数。SELECT
    query否结果集的过滤条件，遵循 MongoDB 风格语法。WHERE
    groupby否维度分组，可包含时间/地域层级设置。GROUP BY
    sort否结果排序，键为字段别名，值为 1/-1。ORDER BY
    limit / skip否结果集分页，默认 limit=20。LIMIT / OFFSET

    扩展字段

    • having：对聚合结果进行二次过滤，语法与 query 相同，但字段名基于 preds/groupby 的别名，对应 SQL 的 HAVING。详见下文"Having 子句"部分。
    • limitBy：按维度限制每组返回条数，可与 ClickHouse 等数据库的 LIMIT N BY field 映射。
    • representation：指定结果渲染方式（表格、图表、指标卡），用于前端展示策略，而非 SQL 语义。详见 Representation。
    • entity_id：实体详情页的上下文，只有在查看某个实体记录时才会附带。

    Having 子句

    having 用于对聚合后的结果进行过滤，与 SQL 的 HAVING 子句对应。它与 query 的主要区别在于：

    特性queryhaving
    作用时机聚合前过滤聚合后过滤
    字段引用原始表字段preds/groupby 的别名
    对应 SQLWHEREHAVING
    能否用聚合函数不能（需子查询）可以

    基本示例

    筛选销售额超过 100 万的地区：

    {
  "schema": "sales",
  "groupby": [{ "_id": "地区", "name": "region" }],
  "preds": [
    { "name": "销售额", "operator": "$sum", "pred": "amount" }
  ],
  "having": {
    "销售额": { "$gt": 1000000 }
  }
}

    对应的 SQL：

    SELECT 地区, SUM(amount) AS 销售额
FROM sales
GROUP BY 地区
HAVING SUM(amount) > 1000000;

    复杂条件

    having 支持与 query 相同的操作符：

    {
  "having": {
    "销售额": { "$gte": 500000, "$lte": 2000000 },
    "订单数": { "$gt": 100 }
  }
}

    与 query 的组合

    {
  "schema": "sales",
  "query": { "日期": { "year": 2024 } },
  "groupby": [{ "_id": "地区" }],
  "preds": [{ "name": "销售额", "operator": "$sum", "pred": "amount" }],
  "having": { "销售额": { "$gt": 1000000 } }
}

    执行顺序：

    1. query 过滤 2024 年的数据
    2. 按 地区 分组并计算销售额
    3. having 过滤销售额 > 100 万的地区

    书写约定

    1. Logicform 必须是一个合法的 JSON 对象，键名使用英文。
    2. 在业务建模阶段为字段配置的别名/翻译会直接出现在 Logicform 中，便于跨团队协作。
    3. 所有字段都支持 嵌套写法（例如 query 中可嵌套子 Logicform），确保复杂算子也能表达。

    了解了整体框架后，可以继续阅读：