Compose Query · DSL 配置式手册（Manual A）

状态：8.x 同步版 · 已同步 timeWindow、CTE / 派生 / Join / Union；底层窗口原语与 SQL 预览仍为规划项 风格定位：以 dsl({...}) 为唯一对外入口的 JSON 配置式查询 DSL；面向 AI 生成、JSON-first 分析师、声明式偏好 镜像手册：链式 API 手册（Manual B） 缺口跟踪：docs/8.3.0.beta/compose-query-manuals-gap-tracker.md 遗留文档：query-dsl.md（基础查询历史参考，未涵盖 CTE / 派生 / 时间窗口）

::: tip 关于"🚧 待补"标记 本手册已补齐 8.x 已验收的 timeWindow、CTE / 派生 / Join / Union 口径。看到 🚧 表示该章节仍属于未公开或未定稿能力，可在 docs/8.3.0.beta/compose-query-manuals-gap-tracker.md 中查看上下文与目标版本。 :::

::: info 决策契约

• 决策 1（功能对齐 ≠ 形态对齐）：本手册与链式 API 手册功能必须等价，但写法可不同——见 gap tracker 中的 Layer 1 / Layer 2 划分
• 决策 2（骨架先行）：能力补齐过程中所有缺口在 gap tracker 留档，本文不直接吞掉
• 决策 3（query-dsl.md deprecated）：旧的 1193 行 query-dsl.md 保留为遗留参考，新功能一律以本手册为准 :::

::: tip DSL 是 first-class 入口（架构验证 2026-04-26） DSL 配置式与链式 API 在 IR 层完全独立——两者各自构造同一份 QueryPlan AST，互不调用、互不依赖。这意味着：

• 使用 DSL 的代码不需要理解链式 API 即可表达完整能力
• timeWindow / 派生 / Join / Union / 计算字段 等高阶能力由 DSL 编译器直接展开为 IR，零绕路
• 未来如整体移除链式 API（仅保留 DSL），本手册的契约不发生任何变化

完整验证结论见 docs/8.3.0.beta/compose-query-manuals-gap-tracker.md 的 G7 closure note。 :::

1. 入门：dsl({...}) 单步查询

1.1 最小示例

const sales = dsl({
  model: "FactSalesQueryModel",
  columns: ["product$id", "product$caption", "salesAmount"],
  slice: [
    { field: "salesDate$id", op: ">=", value: "2025-01-01" }
  ],
  groupBy: ["product$id"],
  orderBy: [{ field: "salesAmount", dir: "desc" }],
  limit: 100
});

return {
  plans: { top_sales: sales },
  metadata: { title: "Top sales by product" }
};

1.2 顶层字段全集

::: warning 字段命名差异（DSL vs 链式 API）

• DSL 使用 slice（不是 where）作为过滤条件字段
• 链式 API 使用 .where([...]) 方法
• 语义完全等价——这是决策 1（功能对齐 ≠ 形态对齐）的体现 :::

1.3 执行语义

• dsl({...}) 返回一个 plan 对象（QueryPlan AST 节点），未立即执行
• 在脚本末尾通过 return { plans: {name: plan}, metadata: {...} } 暴露给宿主
• 引擎按需将每个 plan 编译为 SQL 并在数据源上执行
• plan 对象上仍提供 .join() / .union() 等数据流方法；派生查询使用 dsl({model: prevPlan, ...})（详见 §5-§7）

1.4 与链式 API 的对应关系（速览）

完整互译表见 Manual A · 附录 A / Manual B · 附录 A（两份手册都达 §1-§11 完整后写）。

2. 列与维度引用约定

2.1 引用形式速查

2.2 别名复用（迁移到 §2.5 · 见 §2.4 末尾）

2.3 输出列名映射规则

引擎返回结果时，字段路径中的 . 转为 _：

2.4 列项对象语法（F4 · G5 Phase 1）

除字符串短写形态外，columns 数组也接受对象形态 {field, agg?, as?}，用于显式表达聚合 + alias，避免依赖字符串拼接：

dsl({
  model: "FactSalesQueryModel",
  columns: [
    "product$id",                                          // F1 字符串短写
    { field: "salesAmount", agg: "sum", as: "totalSales" }, // F4 对象（显式聚合）
    { field: "amount", agg: "avg", as: "avgPrice" },       // F4 对象
    { field: "orderDate", agg: "max", as: "lastOrder" },   // F4 对象（非数值聚合）
    "YEAR(orderDate) AS orderYear"                         // F3 字符串（函数表达式仍用字符串）
  ],
  groupBy: ["product$id"]
});

F4 字段定义

字符串 ↔ 对象等价映射

count_distinct 特殊说明

agg: "count_distinct" 自动 lower 为 SQL COUNT(DISTINCT field)：

{ field: "customer_id", agg: "count_distinct", as: "uniqueCustomers" }
// → SQL: COUNT(DISTINCT customer_id) AS uniqueCustomers

Plain alias-only 形态语义（v2-patch-2）

{field, as} 不带 agg 时（plain alias-only），引擎将其合成为请求级 CalculatedFieldDef(origin=PLAIN_ALIAS)，等价于 SQL base AS alias。元数据自动从 base 字段继承：

// 简单重命名 — 类型 / caption 全继承
{ field: "salesAmount", as: "revenue" }
// → SQL: t0.sales_amount AS revenue
// → caption: "销售金额"（从 salesAmount 继承）

// chain rename — 链式 alias 也支持
columns: [
  { field: "salesAmount", as: "x" },
  { field: "x", as: "y" }
]
// → SELECT t0.sales_amount AS x, t0.sales_amount AS y FROM ...

限制：维度后缀字段不能用 plain alias

{field, as} 中 field 含 $ 后缀（维度成员）时不支持，引擎抛 COLUMN_DIMENSION_ALIAS_NOT_SUPPORTED。维度成员的结构化语义在 calc field 路径会扁平化丢失，强制使用基础字段或在 G11/G12 框架内处理。

// ❌ 不支持
{ field: "product$id", as: "productId" }   // → COLUMN_DIMENSION_ALIAS_NOT_SUPPORTED

// ✅ 直接使用维度成员
"product$id"

错误码（F4 校验）

🚧 F5 待补：plan-qualified 形态 {plan: <ref>, field, as}（用于 join 后置消歧）—— Java 引擎链路已落地（G10 PR2/PR3/PR4），当前 g10Enabled() 默认 OFF；用户级开放等待默认值切换决策 + Python PR5 跨语言对齐。如临时遇到 join 后重名冲突，请用源 plan 构造期 rename（即 "name AS alias"）。详见 docs/8.3.0.beta/P0-SemanticDSL-列项对象语法-后置消歧设计.md。

2.5 别名复用

columns 中通过 AS、F4 对象的 as、或 calculatedFields 中通过 name 定义的别名，可在同一 plan 后续位置引用：

dsl({
  model: "FactSalesQueryModel",
  columns: ["YEAR(orderDate) AS orderYear", "SUM(amount) AS totalSales"],
  groupBy: ["orderYear"],            // ← 引用别名 orderYear
  orderBy: [{ field: "totalSales", dir: "desc" }]   // ← 引用别名 totalSales
});

3. 过滤 / 分组 / 排序 / 分页

3.1 slice 算子目录

3.2 逻辑组合：$or / $and

slice: [
  { $or: [
    { field: "status", op: "=", value: "PENDING" },
    { field: "status", op: "=", value: "PROCESSING" }
  ]},
  { field: "amount", op: ">", value: 1000 }   // 顶层数组隐式 AND
]

3.3 字段间比较：$field

slice: [
  { field: "actualEndDate", op: ">", value: { $field: "plannedEndDate" } }
]
// 等价 SQL: actualEndDate > plannedEndDate

3.4 groupBy

// 简写
groupBy: ["customer$id", "product$category"]

// 完整对象
groupBy: [
  { field: "customer$id" },
  { field: "totalAmount", agg: "SUM" }
]

3.5 orderBy

// 简写（- 前缀表示 desc）
orderBy: ["-salesAmount", "orderId"]

// 完整对象
orderBy: [
  { field: "salesAmount", dir: "desc" },
  { field: "orderId", dir: "asc" }
]

3.6 分页

{
  start: 0,            // 起始偏移（从 0 开始）
  limit: 20,           // 每页大小
  returnTotal: true    // 是否在结果元信息中附带总记录数
}

4. 计算字段

4.1 顶层 calculatedFields 数组

计算字段在顶层 calculatedFields 数组中定义（不在 columns 中内联）：

dsl({
  model: "FactSalesQueryModel",
  calculatedFields: [
    {
      name: "profitRate",
      caption: "利润率(%)",
      expression: "profit / sales * 100",
      agg: "SUM"          // 该计算字段被聚合时使用的聚合函数
    },
    {
      name: "netAmount",
      expression: "salesAmount - returnAmount"
    }
  ],
  columns: ["product$id", "profitRate", "netAmount"],   // ← 像普通字段一样引用
  slice: [{ field: "profitRate", op: ">", value: 20 }],  // ← slice 也能引用
  groupBy: ["product$id"]
});

4.2 表达式支持的运算与函数

完整 formula 语法参考 v1.4 spec；本手册不重复罗列。

4.3 引用规则

• 计算字段定义后可在 columns / slice / orderBy / groupBy 中按 name 引用（如普通字段）
• 计算字段可引用其他已定义的计算字段（递归依赖会展开到基础列）
• 禁止循环依赖——引擎检测到会报错
• 表达式依赖级列权限校验：fieldAccess / deniedColumns 会按表达式实际引用的基础字段做白名单校验，无法解析的表达式 fail-closed

在 timeWindow 上下文中，执行顺序固定为：

1. 先按基础度量和 targetMetrics 展开时间窗口
2. 再在外层投影执行后置标量 calculatedFields

因此：

• timeWindow.targetMetrics 只能引用 QM 原生聚合度量，不能引用请求内 calculatedFields
• 后置 calculatedFields 可以引用 timeWindow 输出列，例如 salesAmount__prior、salesAmount__diff、salesAmount__ratio
• 后置 calculatedFields 只能做标量表达式，不允许再声明 agg、windowFrame、partitionBy、windowOrderBy 等窗口或聚合语义
• 如果字段权限拒绝了表达式依赖的基础列，整体 fail-closed

示例：

dsl({
  model: "FactSalesQueryModel",
  columns: ["salesDate$id", "salesAmount", "客单价同比变化"],
  groupBy: ["salesDate$id"],
  timeWindow: {
    field: "salesDate$id",
    grain: "month",
    comparison: "yoy",
    value: ["2025-01-01", "2026-01-01"],
    targetMetrics: ["salesAmount"]
  },
  calculatedFields: [
    {
      name: "客单价同比变化",
      expression: "salesAmount__ratio * 100"
    }
  ]
});

5. 派生查询：dsl({ model: prevPlan, ... })

派生查询把上一个 QueryPlan 当作新的输入模型，再继续过滤、投影、聚合或排序。公开 DSL 形态使用 model: prevPlan；早期实验里的 source 写法不要在新文档和新用法中继续扩散。

const base = dsl({
  model: "FactSalesQueryModel",
  columns: ["product$id", "sum(salesAmount) as totalSales"],
  groupBy: ["product$id"]
});

const filtered = dsl({
  model: base,
  columns: ["product$id", "totalSales"],
  slice: [{ field: "totalSales", op: ">", value: 100000 }],
  orderBy: [{ field: "totalSales", dir: "desc" }]
});

派生查询的列空间来自上一层 plan 的输出 schema：

• 只能引用上一层已经投影出来的列
• 不能越过上一层直接引用底层模型字段
• 聚合后的别名会成为下一层可引用字段
• 字段治理仍然按表达式依赖的底层字段追溯校验

常见错误：

6. Join：plan.join(...)

Join 的公开入口是 plan 组合方法 .join()。8.x 设计已明确不提供 dsl({ join: ... }) 配置式入口，避免在 JSON 对象中引入过多计划图结构。

const salesByProduct = dsl({
  model: "FactSalesQueryModel",
  columns: ["product$id", "sum(salesAmount) as totalSales"],
  groupBy: ["product$id"]
});

const returnsByProduct = dsl({
  model: "FactReturnQueryModel",
  columns: ["product$id", "sum(returnAmount) as totalReturns"],
  groupBy: ["product$id"]
});

const joined = salesByProduct.join(returnsByProduct, "inner", [
  { left: "product$id", op: "=", right: "product$id" }
]);

约束：

• join 类型支持 inner / left / right / full；full 受 SQL 方言能力限制，不支持时 fail-closed 或降级由编译器策略决定
• on 条件必须是等值条件，可写多键
• 不支持公开非等值 join、自连接、跨数据源 join
• 当左右两侧存在同名非键列时，必须通过上游投影 alias 消除歧义

常见错误：

7. Union：plan.union(...)

Union 的公开入口是 plan 组合方法 .union()。8.x 设计已明确不提供 dsl({ union: [...] }) 配置式入口。

const online = dsl({
  model: "OnlineOrderQueryModel",
  columns: ["orderNo", "customer$id", "salesAmount"]
});

const offline = dsl({
  model: "OfflineOrderQueryModel",
  columns: ["orderNo", "customer$id", "salesAmount"]
});

const allOrders = online.union(offline, { all: true });

也可以一次合并多个 plan：

const allOrders = online.union([offline, partner], { all: true });

约束：

• 默认按 UNION 去重；{ all: true } 对应 UNION ALL
• 列按左侧 plan 的输出 schema 对齐
• 所有分支的列数和兼容类型必须一致
• Union 之后可继续作为派生 model 输入做过滤、排序或聚合

常见错误：

8. CTE 复用与命名 plans

CTE 是编译器内部优化，不是用户显式声明语法。多次引用同一个 QueryPlan 时，引擎会自动识别公共子计划，在支持 CTE 的方言上编译为 WITH ... AS (...)；不支持或不适合 CTE 的场景会退回派生子查询。

const productSales = dsl({
  model: "FactSalesQueryModel",
  columns: ["product$id", "sum(salesAmount) as totalSales"],
  groupBy: ["product$id"]
});

const highValue = dsl({
  model: productSales,
  columns: ["product$id", "totalSales"],
  slice: [{ field: "totalSales", op: ">", value: 100000 }]
});

const ranked = dsl({
  model: productSales,
  columns: ["product$id", "totalSales"],
  orderBy: [{ field: "totalSales", dir: "desc" }],
  limit: 20
});

上例中 productSales 被两个下游 plan 复用，编译器可把它提升为公共 CTE。

公开边界：

• 用户不需要、也不能手工指定 CTE 名称
• 顶层返回多个 plan 时，业务侧的 plan 名称只用于结果映射，不等于 SQL CTE 名称
• 不支持递归 CTE
• 不支持把任意 SQL 文本注入为 CTE

9. 时间窗口语义层（高层快捷方式）

9.1 顶层 timeWindow 对象

dsl({
  model: "FactSalesQueryModel",
  columns: ["salesDate$id", "salesAmount"],
  groupBy: ["salesDate$id"],
  timeWindow: {
    field: "salesDate$id",
    grain: "month",
    comparison: "yoy",
    value: ["2024-01-01", "2025-01-01"],
    targetMetrics: ["salesAmount"]
  }
});

9.2 timeWindow 字段全集

9.3 各 comparison 含义

9.4 grain × comparison 兼容矩阵

❌ 表示不合法组合，引擎报 TIMEWINDOW_GRAIN_INCOMPATIBLE。

9.5 输出列后缀

参考 §11 输出后缀规约。

9.6 错误码

9.7 前置条件清单

使用 timeWindow 前必须满足：

1. field 对应的 TM 字段标注了 timeRole = business_date
2. 选择的 grain 与 comparison 在 §9.4 矩阵中是 ✅
3. 如果提供 value，必须恰好两个值，且都是合法日期或相对表达式
4. targetMetrics 中列出的字段是聚合度量（不是普通维度）

10. 时间窗口原语层（底层窗口函数）

🚧 待补：参考 docs/8.3.0.beta/compose-query-manuals-gap-tracker.md 的 G3。

底层 IR 已实现（OverClause / WindowColumn / WindowFrame · v1.5 Java），但 DSL 形态未确定。待决策：列项级别 {field, agg, over: {...}, as} vs 顶层 dsl({window: {...}})。

11. 输出后缀规约

timeWindow 启用时，每个 targetMetric 会按 comparison 模式自动生成附加列。命名规则：

示例

输入：

timeWindow: {
  field: "salesDate$id",
  grain: "month",
  comparison: "yoy",
  value: ["2024-01-01", "2025-01-01"],
  targetMetrics: ["salesAmount"]
}

输出列（在原 salesAmount 之外追加）：

• salesAmount（当期）
• salesAmount__prior（去年同期）
• salesAmount__diff（差值）
• salesAmount__ratio（同比增长率）

Override

当前不支持 override 默认后缀。如需自定义列名，可在结果消费侧做 alias 映射。如未来需要 override，将作为新 gap 登记。

12. 错误码与诊断

🚧 待补

待覆盖：

• §9.6 timeWindow 错误码（已就绪）
• 沙箱错误码（与 docs/8.2.0.beta/P0-ComposeQuery-沙箱白名单错误码与防护用例清单.md 对齐）
• DSL 解析阶段错误（缺字段 / 类型不匹配 / 算子不存在）
• 治理层错误（fieldAccess / deniedColumns 拒绝）

13. 真值 SQL 编译预览（4 方言）

🚧 待补

要覆盖：

• MySQL / PostgreSQL / MSSQL / SQLite 编译差异
• CTE / 子查询 fallback 策略（与 v1.5 P1 spec 对齐）

附录 A · DSL ↔ 链式 API 互译表

🚧 待补：两本手册都达 §1-§11 完整后再写

预览结构：

附录 B · 从 query-dsl.md 迁移

🚧 待补：query-dsl.md 加 deprecation banner 时同步起草

预期内容：

• 字段引用：完全继承 $id / $caption 后缀（已在本手册 §2）
• 操作符：完全继承（已在本手册 §3.1）
• 新增能力指引（CTE / 派生 / timeWindow，分别指向本手册 §5-§8 / §9）

维护记录