StarRocks array_length 函数详解语法、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/starrocksarray_length是 StarRocks 中用于获取数组元素个数的标量函数它接受任意类型的 ARRAY 值并返回 INT 类型结果且拥有cardinality()别名。本文基于官方文档 array_length 参考结合 FE 端函数注册与 BE 端向量化实现源码系统讲解其语法、边界语义NULL、空数组、嵌套数组、底层实现原理与典型实战场景帮助你准确、高效地在 SQL 中使用该函数。函数概述array_length返回一个数组中的元素个数结果类型为INT。它适用于 StarRocks 的 ARRAY 数据类型可作用于任意元素类型的数组包括嵌套数组。该函数有一个等价别名 cardinality()二者在语义、语法与返回值上完全一致。根据官方文档说明cardinality别名自 v3.0 起支持。在 FE 端两个函数名分别以常量形式注册于 FunctionSet.java 中ARRAY_LENGTH array_length与CARDINALITY cardinality因此你在 SQL 中书写array_length(arr)或cardinality(arr)均会被解析并路由到同一实现。语法与参数INT array_length(any_array)参数说明any_array需要统计元素个数的 ARRAY 值元素类型不限数值、字符串、日期、嵌套数组等均可返回值类型固定为INT32 位有符号整数。参数类型解析走多态函数机制FE 端通过ANY_ARRAY伪类型完成类型推导相关逻辑见 PolymorphicFunctionAnalyzer.java 中的注释说明resolve single pseudo type parameter, example: int array_length(ANY_ARRAY)因此无论数组元素是INT、VARCHAR还是嵌套ARRAY都能被统一匹配。返回值与 NULL 语义array_length的返回值遵循三条明确规则理解它们对写出无歧义的查询至关重要结果类型为 INT统计的是数组第一层元素个数不递归统计嵌套数组内部元素。输入为 NULL 时结果为 NULL即array_length(NULL)返回 NULL而不是 0。NULL 元素计入长度数组中存在的NULL元素如[1, 2, 3, NULL]会被计入总数。这三条语义均可通过 BE 端单元测试印证见 array_functions_test.cpp测试覆盖了空数组[]、NULL 数组、[NULL]、[1]、[1,2]等输入其中空数组返回 0、NULL 数组返回 NULL、[NULL]返回 1验证了NULL 元素计入长度的设计测试还特意断言array_length不会修改输入列的 nullable 空值位图array_length should not mutate input nullable null bitmap说明该函数对输入列是只读的。完整示例以下示例均可在 StarRocks MySQL 客户端中直接执行输出与官方文档一致基础用法统计一维数组元素个数mysql select array_length([1,2,3]); ----------------------- | array_length([1,2,3]) | ----------------------- | 3 | ----------------------- 1 row in set (0.00 sec)NULL 元素计入长度mysql select array_length([1,2,3,null]); ------------------------------- | array_length([1, 2, 3, NULL]) | ------------------------------- | 4 | -------------------------------注意[1,2,3,NULL]虽然最后一个元素为 NULL但数组整体有 4 个槽位因此返回 4。嵌套数组只统计第一层mysql select array_length([[1,2], [3,4]]); ----------------------------- | array_length([[1,2],[3,4]]) | ----------------------------- | 2 | ----------------------------- 1 row in set (0.01 sec)[[1,2], [3,4]]的外层包含两个子数组因此返回 2而不是 4。别名 cardinality 的等价用法mysql select cardinality([1,2,3]); ----------------------- | cardinality([1,2,3]) | ----------------------- | 3 | ----------------------- 1 row in set (0.00 sec)空数组与 NULL 输入-- 空数组长度为 0 mysql select array_length([]); ------------------ | array_length([]) | ------------------ | 0 | ------------------ -- 对 NULL 求长度返回 NULL mysql select array_length(NULL); -------------------- | array_length(NULL) | -------------------- | NULL | --------------------以上空数组、NULL、[NULL]与嵌套数组的边界行为均在 array_functions_test.cpp 中有对应的单测断言分别期望Datum(0)、kNullDatum、Datum(1)等结果可作为行为基准。源码级实现原理BE 端向量化实现array_length的底层实现位于 array_functions.cpp 的ArrayFunctions::array_length方法并在 array_functions.h 中通过DEFINE_VECTORIZED_FN(array_length)注册为向量化函数。其核心计算思路如下取数通过ColumnHelper::get_data_column拿到ArrayColumn并读取其offsets数组——StarRocks 的ArrayColumn以偏移量数组 连续元素列的方式存储数组即 columnar 布局每个数组在 offsets 中对应一个区间。计算长度对第i行数组其元素个数即为arr_offsets[i 1] - arr_offsets[i]即相邻偏移之差。整个计算是一个无分支的批量循环充分利用向量化执行引擎按列处理的优势。常量列优化当输入是常量列例如SELECT array_length([1,2,3])这类字面量场景时直接构造一个常量Int32Column结果列避免逐行重复计算。NULL 传播当输入列携带 NULL 时将输入的 null 位图原样复制到结果列的NullableColumn中实现输入为 NULL 则结果为 NULL的语义。从实现可以看出array_length的时间复杂度为 O(1) 每行仅做一次偏移量减法性能开销极低这也是它适合在大规模数组列上直接使用的原因。FE 端解析与优化在查询优化阶段FE 对array_length还有数项专门优化值得了解常量折叠FoldConstantsRule支持对array_length([])、array_length([NULL, NULL])等常量表达式在优化阶段直接求值相关代码见 FoldConstantsRule.java避免运行时计算。子字段裁剪PruneSubfieldRule在裁剪数组子字段访问路径时会正确处理array_length(v)这类只依赖数组 offsets、不依赖元素内容的表达式见 PruneSubfieldRule.java 中的注释说明array_length可以基于保留 offsets、丢弃元素的裁剪后数组继续计算。物化视图改写在聚合物化视图重写中array_length(array_unique_agg(x))可作为count(distinct x)的等价分解形式参与匹配与改写相关等价规则见 ArrayRewriteEquivalent.java 与 AggregatePushDownUtils.java。实战场景1. 表列上的数组长度统计实际业务中数组通常存储在表的 ARRAY 类型列中此时array_length逐行生效-- 统计每行 tags 数组的元素个数 SELECT user_id, array_length(tags) AS tag_cnt FROM user_profiles; -- 过滤出数组元素个数大于 5 的行 SELECT * FROM user_profiles WHERE array_length(tags) 5;2. 与生成列/嵌套函数组合array_length返回 INT可直接参与算术、比较与聚合-- 数组元素个数求和 / 求平均 SELECT sum(array_length(tags)) AS total_tags, avg(array_length(tags)) AS avg_tags FROM user_profiles; -- 结合 array_distinct 统计去重后的元素个数 SELECT array_length(array_distinct(tags)) AS distinct_tag_cnt FROM user_profiles;3. 对嵌套数组逐层处理由于array_length只统计第一层若需统计所有子元素总数可结合array_agg、unnest或逐层取子数组后再调用-- 外层数组长度 SELECT array_length([[1,2], [3,4]]); -- 2 -- 逐层统计先取外层数组再对其元素逐个求长 SELECT array_length([array_length([1,2]), array_length([3,4])]); -- 2外层仍是 2 个子数组4. 与 distinct 计数相关的物化视图优化如前文所述优化器支持将count(distinct x)改写为array_length(array_unique_agg(x))的等价形式用于物化视图匹配。当你的查询模式以精确去重计数为主时理解这一等价关系有助于设计合适的聚合物化视图让array_length在预聚合结果上直接计算从而加速查询。相关说明与延伸阅读别名cardinality() 与array_length完全等价自 v3.0 起支持二者可互换使用。数组相关会话变量StarRocks 提供max_array_length会话变量用于限制单个数组的最大元素个数默认不设限相关定义见 SessionVariable.java在构造超大数组字面量时可能触发校验。测试用例完整的边界行为测试见 array_functions_test.cpp可作为该函数语义的权威参考。关键词检索ARRAY_LENGTH、ARRAY、CARDINALITY。小结array_length是一个轻量、高性能的数组元数据函数理解其NULL 输入返回 NULL、NULL 元素计入长度、只统计第一层三大语义并结合 BE 端偏移量减法实现与 FE 端常量折叠、子字段裁剪、物化视图改写等优化即可在真实数据模型与查询优化中充分发挥其价值。【免费下载链接】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），仅供参考
