如何看懂 Huey 的多阶段 SQL 生成:SqlQueryGenerator 核心实现原理完全解析
如何看懂 Huey 的多阶段 SQL 生成:SqlQueryGenerator 核心实现原理完全解析
Huey 是一款基于 DuckDB-WASM 的浏览器端数据分析(BI)工具,其核心引擎类 SqlQueryGenerator 负责把用户在查询构建器中搭好的查询模型(QueryModel)转换成一串多阶段 SQL,交给 DuckDB 执行并渲染成交互式透视表。本文带你完整拆解这条「查询模型 → 多阶段 SQL」的生成流水线:过滤项如何按嵌套层级分组、UNNEST 展开如何逐层生成 CTE、总计行如何靠 GROUPING SETS 实现。
从查询构建器到 SQL:整体链路
理解 SqlQueryGenerator 之前,先认识它的输入——查询模型。Huey 的查询状态保存在 QueryModel.js 中,由 4 条「轴」构成:
| 轴 | 常量 | 作用 |
|---|---|---|
| 行轴 | AXIS_ROWS |
生成透视表的行表头 |
| 列轴 | AXIS_COLUMNS |
生成透视表的列表头 |
| 单元格轴 | AXIS_CELLS |
放置聚合函数,填充单元格数值 |
| 过滤器轴 | AXIS_FILTERS |
定义 WHERE / QUALIFY 条件 |
每一条轴上的条目都是一个 QueryAxisItem,关键字段包括:
columnName/columnType:列名与数据类型;derivation:派生属性,如从时间戳提取year、month,或对数组做elements展开;aggregator:聚合函数,如sum、count、list;memberExpressionPath:访问 STRUCT / ARRAY / MAP 嵌套字段的路径(JSON 数据尤其常见);includeTotals:是否生成(小)计行。
查询执行时,TupleSet.js(负责轴表头分页)和 CellSet.js(负责单元格数值)都会调用统一入口:
此外,导出对话框 用它导出可复用的 SQL,过滤器面板 用它为筛选值候选列表生成查询——同一个生成器服务全应用。
为什么需要多阶段 SQL(CTE 流水线)?
一条简单的透视表查询本可以写成单个 SELECT。但 Huey 支持三类「单条 SELECT 难以表达」的能力,SqlQueryGenerator 因此把它们拆成多个 CTE 阶段:
- 嵌套数据展开(Unnesting):对数组的
elements、map 的entries等派生属性,需要用unnest()等函数把一行「炸开」成多行;如果展开后又嵌套着展开(例如展开数组里的数组),就必须一层一个 CTE。 - 窗口函数定稿:内置的
row number派生属性和轴聚合(axis aggregate,本质是OVER窗口函数)需要在独立的 CTE 里先算成普通列,最后阶段才能参与 GROUP BY。 - 嵌套路径上的过滤器下推:如果过滤器作用在展开之后的元素上(如「数组元素包含某值」),该条件必须推迟到对应展开阶段之后的 CTE 才能生效。
最终产物形如:
WITH "__huey_data_foundation" AS (SELECT ... FROM <数据源>),
"cte2" AS (SELECT ... FROM "__huey_data_foundation"),
"cte3" AS (SELECT unnest(...) AS ... FROM "cte2")
SELECT ...
FROM ...
GROUP BY GROUPING SETS (...)
ORDER BY ...
阶段一:过滤项按嵌套层级分组
入口方法首先对过滤器轴做预处理,核心逻辑在 #getFilterItemsByNestingStage():
- 先剔除「空过滤器」(没有启用任何值的条目),避免生成无意义的 WHERE 条件;
- 检查每个过滤项的
memberExpressionPath中是否包含展开函数(如unnest()):- 普通过滤项统一放在键为
''的列表里,应用到最底层 CTE; - 需要展开后才可判断的过滤项,以其完整表达式路径字符串(如
tags['elements'])为键存入字典,等待后续阶段认领。
- 普通过滤项统一放在键为
这一步把「哪些过滤条件在哪一层执行」的问题,转化成了一个简单的按路径查找问题。
阶段二:逐层构建 Unnesting CTE
#getUnnestingStages() 是整个生成器最精巧的部分,它按「每发现一层展开操作,就追加一个 CTE」的策略迭代:
1. 奠基 CTE __huey_data_foundation:直接引用数据源的 FROM 子句(如 read_csv('...')),顶层过滤项挂在这一层。
2. row number 专用层:如果轴上存在内置 row number 派生属性,会额外插入 cte2,把 ROW_NUMBER() OVER () 窗口函数先物化成一列普通值。
3. 循环寻找展开操作:每一轮遍历当前 CTE 的所有项,在 memberExpressionPath 中查找展开函数(unnest()、generate_subscripts() 等,注册表来自 AttributeUi.arrayDerivations):
- 找到后,在当前 CTE 里记录一个
unnestingOperationItem,描述「展开哪个列、元素类型是什么、需要调用哪些展开函数」; - 属于同一展开层级的项被重写:列名改为
原列.路径.展开函数(如tags['elements']),路径前缀被裁掉,剩余路径留给下一轮; - 同时调用 #transformFilterItems():把路径前缀匹配当前展开层的过滤器改写到展开后的新列上;改写后路径中若还有更深的展开操作,就留待后续阶段,否则直接挂到当前 CTE 的过滤列表。
4. 循环终止:当某轮找不到新的展开操作时,整个 CTE 链构建完成。嵌套几层展开,就生成几条 CTE,层级再深也不会丢失语义。
阶段三:轴聚合的「定稿」层
如果轴上存在轴聚合项(如「按城市分区的销售额合计」这类窗口函数),或过滤器本身就是聚合条件,getSqlSelectStatementForAxisItems() 会调用 #createAxisAggregateStage() 在链尾再追加一个 CTE:把窗口函数表达式计算成以条目标题为别名的普通列,这样最后阶段才能安全地对它们做 GROUP BY。
最终阶段:GROUP BY、总计与排序
最后一条 SELECT 由 #getSqlSelectStatementForFinalStage() 生成,包含三个关键机制:
① 双轴分组的 GROUP BY:行轴和列轴的表达式分别累积到两个 GROUP BY 表达式列表中,最后合并——这正是透视表「行列交叉分组」的 SQL 表达。
② 总计行 = GROUPING SETS + GROUPING_ID:遇到 includeTotals 的轴项时,生成器把「当前已累积的分组表达式」快照进该轴的 grouping sets 列表,行轴与列轴的 sets 再两两交叉组合,输出 GROUP BY GROUPING SETS (...)。同时插入:
GROUPING_ID(...) AS "__huey_grouping_id"
__huey_grouping_id(定义见 TupleSet.js)是一个位掩码,前端结果集靠它识别「哪一行是总计、属于哪个分组」。更妙的是排序:每个总计列的 ORDER BY 项被替换为对分组 ID 的位运算(如 __huey_grouping_id & (1 << n) ASC),保证总计行紧贴其所属分组,而不是被普通排序打散。
③ 行计数窗口:当需要知道轴上总元组数时(分页、进度提示),追加 COUNT(*) OVER () 表达式随行数据一起返回。
过滤条件由 #generateSqlClausesForFilterItems() 按性质分流:普通项生成 WHERE 子句,聚合项生成 DuckDB 的 QUALIFY 子句(对窗口函数结果过滤)。
组装与采样:WITH 子句的拼接
回到 入口方法,所有中间 CTE 经 #getSqlSelectStatementForIntermediateStage() 渲染为 "cte2" AS ( SELECT ... ) 文本后拼接:
- 采样下推:
USING SAMPLE子句只加在最底层 CTE 上(index === 0),且仅当没有其他中间层时才对最终查询生效——即「先抽样、再展开、再聚合」,大幅降低大数据量下的响应时间; finalStateAsCte选项:CellSet 需要把行/列/单元格三条查询组合执行,此时最终 SELECT 会被包进一个具名 CTE,供上层拼装;- 若整条链没有任何中间 CTE,则退化为一条朴素的
SELECT ... FROM 数据源 WHERE ... GROUP BY ...,不会多此一举。
小结
SqlQueryGenerator 的设计精髓可以概括为三句话:
- 分而治之:把嵌套展开、窗口定稿、聚合分组三种复杂度不同的操作,拆进各自独立的 CTE 阶段,每层只解决一个问题;
- 过滤器随层走:过滤条件按嵌套路径预分组,在能执行的最早一层落地,兼顾正确性与性能;
- 总计交给数据库:GROUPING SETS + GROUPING_ID 位运算让「行内总计」完全在 SQL 层完成,前端只负责按掩码识别展示。
想继续深挖,建议按 QueryModel.js → QueryAxisItem.js(单项 SQL 表达式生成)→ SqlQueryGenerator.js(多阶段编排)的顺序阅读源码,即可完整还原 Huey 从查询模型到多阶段 SQL 的全部实现。
