StarRocks SUM 聚合函数详解：语法、返回类型映射、NULL 处理与源码实现机制

StarRocks SUM 聚合函数详解语法、返回类型映射、NULL 处理与源码实现机制【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks本篇技术文章以 StarRocks 官方文档中的 SUM 函数说明 为主体系统讲解SUM的语法、参数、返回值类型映射、NULL 忽略行为与隐式类型转换规则并完整保留官方文档中的建表与查询示例在此基础上结合前端FE函数注册源码 FunctionSet.java 与后端BE聚合执行器 aggregator.h 的实现深入剖析SUM在各数据类型下的返回类型推导与聚合计算流程。读完后你既能正确编写含SUM的分析查询也能理解 StarRocks 在解析器层面如何为SUM选择正确的返回类型以及 VARCHAR 列隐式转 DOUBLE 的底层依据。一、功能概述SUM是 StarRocks 提供的聚合函数用于返回表达式expr中所有非 NULL 值的和。文档明确指出可以配合DISTINCT关键字对去重后的非 NULL 值求和SUM([DISTINCT] expr)这一语法形式在 聚合函数总览页 所属的文档体系中SUM与AVG、COUNT、MIN、MAX、STDDEV等共同构成多维分析与实时分析场景中最基础的一组聚合原语。二、参数说明参数说明支持的数据类型expr求值结果为数值的表达式TINYINT、SMALLINT、INT、FLOAT、DOUBLE、DECIMAL官方文档给出的支持类型列表是“常用类型视角”。而从 FE 源码注册逻辑看实际注册的类型覆盖面更广registerBuiltinSumAggFunction方法会遍历FloatType.FLOAT_TYPES、IntegerType.INTEGER_TYPES、DecimalType.DECIMAL_TYPES三组类型族逐一注册聚合函数实例因此 SMALLINT、BIGINT、LARGEINT、DECIMAL32/64/128/256 等变体在解析阶段都有对应的内置注册项见 FunctionSet.java#L1714-L1742。文档中列出的 TINYINT/SMALLINT/INT/FLOAT/DOUBLE/DECIMAL 是最常见的用户输入类型。三、返回值输入类型到返回类型的映射这是SUM函数行为中最容易被开发者忽视、却直接影响结果列类型与精度的部分。官方文档给出的映射规则如下输入类型返回类型TINYINTBIGINTSMALLINTBIGINTINTBIGINTFLOATDOUBLEDOUBLEDOUBLEDECIMALDECIMAL上述映射并非文档的孤立约定而是 FE 在启动时注册聚合函数时逐一写死在注册逻辑中的。对应源码位于 FunctionSet.java#L1714-L1742浮点族FLOAT_TYPES含 FLOAT 与 DOUBLESUM的中间结果类型与最终结果类型都注册为FloatType.DOUBLE与文档中FLOAT - DOUBLE、DOUBLE - DOUBLE一致整型族INTEGER_TYPES若输入为LARGEINT返回类型保持LARGEINT其余整数类型TINYINT/SMALLINT/INT/BIGINT统一注册返回IntegerType.BIGINT这正是文档中三行- BIGINT映射的实现来源十进制族DECIMAL_TYPES输入为 DECIMAL256 时返回 DECIMAL256否则统一升宽为DecimalType.DECIMAL128对应文档中DECIMAL - DECIMAL的表述。源码中同时留有一个TODO(stephen): support auto scale up decimal precision注释可以推断当前实现对 DECIMAL 的精度/scale 未做自动扩展跨精度场景下建议关注该限制。值得注意的一个设计细节整型输入一律升宽为 BIGINT 返回意味着即使对TINYINT列求和结果列也是 64 位整数为累加过程中的数值增长预留了空间而LARGEINT64 位整型则原样保留。这种“输入窄化升宽、输入最宽保持”的策略与返回类型注册一一对应。四、使用注意事项Usage Notes官方文档列出了三条使用注意事项每一条都有明确的实现依据值得逐条展开4.1 忽略 NULL 值This function ignores nulls.SUM在累加过程中直接跳过 NULL 输入而不是把 NULL 当作 0 或产生 NULL 结果除非组内全部为 NULL。后文的示例 2 将专门演示这一行为。4.2 表达式不存在时报错An error is returned ifexprdoes not exist.当SUM的参数不是合法表达式例如引用了不存在的列时分析阶段即返回错误不会进入执行阶段。4.3 VARCHAR 输入的隐式转换If a VARCHAR expression is passed, this function implicitly casts the input into DOUBLE values. If the cast fails, an error is returned.这是SUM最“宽容”也最危险的一条行为对字符串列求和时StarRocks 会隐式地把每个值转换为 DOUBLE再累加。转换成功则按 DOUBLE 语义求和某个值无法转换例如字符串abc时返回错误。官方文档的示例 3 正是基于这一规则对STRING类型的hobby列执行SUM(DISTINCT hobby)。五、完整实战示例继承官方文档操作链路以下示例完整继承官方文档中的四步操作链路建表 → 插入数据 → 验证数据 → 四种SUM用法。5.1 创建示例表 employeesCREATE TABLE IF NOT EXISTS employees ( region_num TINYINT COMMENT range [-128, 127], id BIGINT COMMENT range [-2^63 1 ~ 2^63 - 1], hobby STRING NOT NULL COMMENT upper limit value 65533 bytes, income DOUBLE COMMENT 8 bytes, sales DECIMAL(12,4) COMMENT ) DISTRIBUTED BY HASH(region_num);该表刻意混合了TINYINT、BIGINT、STRING、DOUBLE、DECIMAL五类列正好覆盖SUM的主要类型路径其中income列将插入一个 NULL 值用于演示 NULL 忽略行为。5.2 插入数据INSERT INTO employees VALUES (3,432175,3,25600,1250.23), (4,567832,3,37932,2564.33), (3,777326,2,null,1932.99), (5,342611,6,43727,45235.1), (2,403882,4,36789,52872.4);注意第三行id 777326的income为 NULL这是后续示例 2 的伏笔。5.3 验证表数据MySQL select * from employees; ----------------------------------------------- | region_num | id | hobby | income | sales | ----------------------------------------------- | 5 | 342611 | 6 | 43727 | 45235.1000 | | 2 | 403882 | 4 | 36789 | 52872.4000 | | 4 | 567832 | 3 | 37932 | 2564.3300 | | 3 | 432175 | 3 | 25600 | 1250.2300 | | 3 | 777326 | 2 | NULL | 1932.9900 | ----------------------------------------------- 5 rows in set (0.01 sec)5.4 示例 1按区域计算销售总额MySQL SELECT region_num, sum(sales) from employees group by region_num; ------------------------ | region_num | sum(sales) | ------------------------ | 2 | 52872.4000 | | 5 | 45235.1000 | | 4 | 2564.3300 | | 3 | 3183.2200 | ------------------------ 4 rows in set (0.01 sec)sales是DECIMAL(12,4)列返回值保持 DECIMAL 语义3183.2200 1250.2300 1932.9900与第三节“DECIMAL - DECIMAL”的映射一致。5.5 示例 2NULL 值被忽略MySQL select region_num, sum(income) from employees group by region_num; ------------------------- | region_num | sum(income) | ------------------------- | 2 | 36789 | | 5 | 43727 | | 4 | 37932 | | 3 | 25600 | ------------------------- 4 rows in set (0.01 sec)region_num 3的组内有两条记录但id 777326的income为 NULL 未被计入因此结果为单值25600。这正是“SUM ignores nulls”规则的直观验证如果实现是“遇到 NULL 整组返回 NULL”该组的输出将是 NULL 而非 25600。5.6 示例 3STRING 列隐式转 DOUBLE 求和 DISTINCTMySQL select sum(DISTINCT hobby) from employees; --------------------- | sum(DISTINCT hobby) | --------------------- | 15 | --------------------- 1 row in set (0.01 sec)hobby列是STRING类型其值为3,3,2,6,4。按第 4.3 节的规则每行值先被隐式转换为 DOUBLE再按DISTINCT去重得到{3, 2, 6, 4}求和得15。这个例子同时验证了两个行为字符串隐式数值转换以及DISTINCT修饰符对非 NULL 去重值的求和。5.7 示例 4配合 WHERE 过滤后求和MySQL select sum(income) from employees WHERE income 30000; ------------- | sum(income) | ------------- | 118448 | ------------- 1 row in set (0.00 sec)过滤条件income 30000保留了 37932、43727、36789 三行25600 被过滤合计118448。SUM与WHERE组合时求和作用于过滤后的行集合这是聚合函数与谓词下推协同的常规用法。六、源码级机制补充SUM 在 StarRocks 中的注册与执行6.1 FE 侧聚合函数的类型化注册SUM作为内置聚合函数在 FE 启动阶段由 FunctionSet.java 完成注册入口是registerBuiltinSumAggFunction(SUM)FunctionSet.java#L1514。注册过程通过AggregateFunction.createBuiltin(name, 输入类型, 中间结果类型, 最终结果类型, ...)为每一个具体的输入类型创建一条聚合函数实例参数中的中间结果类型与最终结果类型共同决定了分布式聚合各阶段的输出类型从源码结构看整型路径中除 LARGEINT 外的所有整数类型统一以IntegerType.BIGINT作为中间与最终类型注册浮点路径中 FLOAT 与 DOUBLE 均以FloatType.DOUBLE注册中间与最终类型DECIMAL 路径按 DECIMAL128/DECIMAL256 宽化处理。这种“按类型逐一注册”的机制保证了类型推导发生在 FE 分析/规划阶段用户写SUM(sales)时返回列的类型在物理计划生成前就已经确定BE 无需再做运行时类型协商。这也是文档中返回类型映射表能够精确给出的根本原因。6.2 BE 侧向量化聚合执行在 BE 端聚合算子由执行器中的聚合器框架承载be/src/exec/aggregator.h 定义了聚合执行的核心流程其注释明确描述了“消费完全部输入行后再进行 aggregate/finalize 处理”的分阶段模型。SUM的执行遵循该通用框架各执行线程对分片数据累加得到部分结果最终阶段完成合并输出。与 FE 的类型化注册配合BE 侧按注册好的中间/最终类型完成数值累加整型以 64 位宽度累加以避免溢出。如果你需要验证SUM在不同类型下的行为可以参考 BE 聚合相关测试目录 be/test/exec/ 与通用测试框架 be/test/test_main.cpp。七、相关函数SUM位于 StarRocks 聚合函数体系之中文档目录 docs/en/sql-reference/sql-functions/aggregate-functions/ 下提供了与之配套的常用聚合函数文档可按需延伸阅读multi_distinct_sum对多列分别去重后求和avg平均值聚合count计数聚合min_max / max最小值/最大值。八、小结SUM([DISTINCT] expr)是 StarRocks 多维分析场景中最常用的聚合原语之一。掌握它的关键有三点一是返回类型映射——整数升宽为 BIGINT、浮点归一到 DOUBLE、DECIMAL 保持 DECIMALDECIMAL128/256二是NULL 语义——累加过程直接跳过 NULL三是字符串隐式转换——VARCHAR/STRING 输入按 DOUBLE 语义转换求和转换失败则报错。FE 侧的类型化注册FunctionSet.java决定了前两点在规划期即被固化BE 侧的向量化聚合框架aggregator.h则在执行期高效完成累加与合并。【免费下载链接】starrocksThe worlds fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考