如何看懂 Huey 的多阶段 SQL 生成:SqlQueryGenerator 核心实现原理完全解析

原创2026-11-14 19:48:411,937 阅读

如何看懂 Huey 的多阶段 SQL 生成:SqlQueryGenerator 核心实现原理完全解析

Huey 是一款基于 DuckDB-WASM 的浏览器端数据分析(BI)工具,其核心引擎类 SqlQueryGenerator 负责把用户在查询构建器中搭好的查询模型(QueryModel)转换成一串多阶段 SQL,交给 DuckDB 执行并渲染成交互式透视表。本文带你完整拆解这条「查询模型 → 多阶段 SQL」的生成流水线:过滤项如何按嵌套层级分组、UNNEST 展开如何逐层生成 CTE、总计行如何靠 GROUPING SETS 实现。

Huey 数据透视表界面:SqlQueryGenerator 将查询模型转换为多阶段 SQL

从查询构建器到 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(负责单元格数值)都会调用统一入口:

SqlQueryGenerator.getSqlSelectStatementForAxisItems()

此外,导出对话框 用它导出可复用的 SQL,过滤器面板 用它为筛选值候选列表生成查询——同一个生成器服务全应用。

为什么需要多阶段 SQL(CTE 流水线)?

一条简单的透视表查询本可以写成单个 SELECT。但 Huey 支持三类「单条 SELECT 难以表达」的能力,SqlQueryGenerator 因此把它们拆成多个 CTE 阶段:

  1. 嵌套数据展开(Unnesting):对数组的 elements、map 的 entries 等派生属性,需要用 unnest() 等函数把一行「炸开」成多行;如果展开后又嵌套着展开(例如展开数组里的数组),就必须一层一个 CTE。
  2. 窗口函数定稿:内置的 row number 派生属性和轴聚合(axis aggregate,本质是 OVER 窗口函数)需要在独立的 CTE 里先算成普通列,最后阶段才能参与 GROUP BY。
  3. 嵌套路径上的过滤器下推:如果过滤器作用在展开之后的元素上(如「数组元素包含某值」),该条件必须推迟到对应展开阶段之后的 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 的设计精髓可以概括为三句话:

  1. 分而治之:把嵌套展开、窗口定稿、聚合分组三种复杂度不同的操作,拆进各自独立的 CTE 阶段,每层只解决一个问题;
  2. 过滤器随层走:过滤条件按嵌套路径预分组,在能执行的最早一层落地,兼顾正确性与性能;
  3. 总计交给数据库:GROUPING SETS + GROUPING_ID 位运算让「行内总计」完全在 SQL 层完成,前端只负责按掩码识别展示。

想继续深挖,建议按 QueryModel.js → QueryAxisItem.js(单项 SQL 表达式生成)→ SqlQueryGenerator.js(多阶段编排)的顺序阅读源码,即可完整还原 Huey 从查询模型到多阶段 SQL 的全部实现。

登录后查看全文
huey