StarRocks array_contains 数组包含判断函数语法、语义与底层实现解析【免费下载链接】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 的array_contains数组函数展开介绍其语法、返回值语义、NULL 匹配规则与多维数组子数组匹配行为并深入 BEBackend向量化执行引擎的源码实现帮助读者在 SQL 查询中正确、高效地使用该函数进行数组成员关系判断。array_contains是 StarRocks 提供的高性能数组成员判断函数用于检查数组中是否包含某个元素。它适用于标签筛选、白名单校验、维度匹配等典型场景与array_contains_all、array_contains_any、array_contains_seq共同构成数组包含关系判断的函数族。读完本文你将掌握其完整语法、边界语义以及它在 StarRocks 向量化引擎中的真实执行路径。函数签名与返回值array_contains的语法定义如下参见 array_contains.mdarray_contains(any_array, any_element)any_array待检查的数组可以是任意元素类型的 ARRAY。any_element要查找的目标元素其类型需与数组元素类型匹配。返回值语义数组包含该元素时返回1不包含时返回0。从 BE 端源码看array_contains的实际实现通过 array_functions.cpp 中的ArrayContainsImplfalse, UInt8Column完成——模板参数PositionEnabledfalse、返回列类型为UInt8Column即返回1或0。这一实现与array_positionPositionEnabledtrue返回Int32Column共享同一套核心逻辑array_functions.cpp两者的差异仅在于最终输出的是是否存在还是元素位置。基础使用示例以下示例均来自官方文档并可直接在 MySQL 客户端中执行1. 判断字符串数组中是否包含某个元素mysql select array_contains([apple,orange,pear], orange); ----------------------------------------------------- | array_contains([apple,orange,pear], orange) | ----------------------------------------------------- | 1 | ----------------------------------------------------- 1 row in set (0.01 sec)2. 判断数值数组中是否包含某个元素SELECT array_contains([1, 2, 3], 4); -- 返回 0NULL 匹配语义array_contains支持对 NULL 元素的匹配判断即你可以检查数组中是否包含 NULLmysql select array_contains([1, NULL], NULL); -------------------------------- | array_contains([1,NULL], NULL) | -------------------------------- | 1 | -------------------------------- 1 row in set (0.00 sec)这一行为在底层有明确的代码支撑在_process内核循环中array_functions.cpp当数组元素与目标元素同为 nullable 时实现会比较两者的 NULL 位图null map只要null_element与null_target同为 NULL 即判定命中若数组中某位置元素为 NULL、目标元素也是 NULL则命中返回1若数组元素为 NULL 而目标元素为非 NULL则跳过该位置继续比较若数组元素非 NULL 而目标元素为 NULL同样不构成匹配。此外当数组元素列不含任何 NULL 而目标值是纯 NULL 列时实现会走快速路径直接返回不包含array_functions.cpp避免无谓的逐元素比较。多维数组与子数组匹配array_contains同样适用于多维数组ARRAY 的 ARRAY。此时目标参数为子数组且要求子数组元素完全精确匹配包括元素排列顺序mysql select array_contains([[1,2,3], [4,5,6]], [4,5,6]); -------------------------------------------- | array_contains([[1,2,3],[4,5,6]], [4,5,6]) | -------------------------------------------- | 1 | -------------------------------------------- 1 row in set (0.00 sec) mysql select array_contains([[1,2,3], [4,5,6]], [4,6,5]); -------------------------------------------- | array_contains([[1,2,3],[4,5,6]], [4,6,5]) | -------------------------------------------- | 0 | -------------------------------------------- 1 row in set (0.00 sec)从第二个示例可以看到[4,6,5]与数组中的[4,5,6]元素集合相同但顺序不同仍返回0。这说明多维数组场景下array_contains执行的是顺序敏感的精确子数组匹配而非集合意义上的元素子集判断。若你需要判断的是顺序不敏感的包含关系应使用array_contains_all若需要判断子序列关系则可参考array_contains_seq其实现采用了类似 KMP 算法的思路来加速子序列匹配见 array_functions.tpp。底层实现上多维数组场景由HANDLE_ELEMENT_TYPE宏对ArrayColumn类型进行分派处理array_functions.cpp子数组之间的比较通过列的equals方法完成array_functions.cpp因此数组元素类型不限于标量还支持嵌套的 ARRAY、JSON、MAP、STRUCT 等复合类型。空数组与边界行为空数组不包含任何元素因此对任意目标元素包括 NULL的array_contains均返回0。该边界行为由 BE 侧单测覆盖见 array_functions_test.cpp 中的array_contains_empty_array用例array_contains([], 1)返回 0INT 类型array_contains([], abc)返回 0VARCHAR 类型array_contains(ARRAYARRAYint[], [1])返回 0嵌套数组类型array_contains(ARRAYARRAYint[], ARRAYint[])返回 0。底层执行原理模板化与向量化array_contains在 BE 端的实现体现了 StarRocks 向量化执行引擎的典型设计1. 类型模板化分派。入口_array_contains_generic会先判断数组列与目标列是否为常量列Const Column随后依据数组元素列是否 nullable、目标是否 nullable、是否常量等组合将任务分派到_process的 8 种模板特化组合中array_functions.cpp。通过编译期模板展开避免运行时类型判断开销。2. 批量循环处理。核心循环按行遍历结果列通过 offset 数组定位每个数组元素的起止下标offsets_ptr[i1] - offsets_ptr[i]逐元素比较array_functions.cpp。对非复合类型直接读取底层连续内存数据做比较elements_data[offset j] targets_data[i]这保证了缓存友好的顺序访问。3. 常量优化。当数组列与目标列都是常量时例如array_contains([1,2,3], 2)直接以字面量调用只计算一次再按结果行数生成 ConstColumnarray_functions.cpp避免重复计算。FE 侧的优化器还会对常量表达式做常量折叠constant foldingconstArrayContains即为array_contains注册的折叠处理逻辑FoldConstantsRule.java。4. 函数注册。array_contains在 FE 端函数目录中注册为FunctionSet.ARRAY_CONTAINSFunctionSet.java同时在 Trino 语法兼容层中Trino 的contains函数会被自动转换为array_containsTrino2SRFunctionCallTransformer.java方便从 Trino 迁移的查询平滑运行。关联函数族与选型建议与array_contains配套的包含关系函数还有均在 array_functions.cpp 中定义函数语义典型场景array_contains(array, element)数组是否包含某元素含 NULL、子数组顺序敏感单个标签 / 成员判断array_contains_all(array, sub_array)数组是否包含子数组中的全部元素集合语义多标签同时命中ANDarray_contains_any(array, sub_array)数组是否包含子数组中的任一元素集合语义多标签任一命中ORarray_contains_seq(array, sub_array)数组是否包含子数组作为连续子序列序列模式匹配其中array_contains_all在实现中通过构建哈希表加速查找array_contains_seq借鉴 KMP 算法思想进行子序列匹配array_functions.tpp在数据量较大时具备良好的性能特性。实际使用中请根据精确成员 / 任意成员 / 全部成员 / 连续子序列四种不同需求选择对应函数。实践建议类型匹配any_element的类型应与数组元素类型一致StarRocks 在类型推导阶段会进行隐式转换校验类型不兼容时会在规划阶段报错。NULL 语义如需过滤包含 NULL 的行array_contains(arr, NULL)是有意支持的能力若业务上不需要 NULL 匹配可在查询前用array_remove(arr, NULL)等函数先行清洗。性能意识array_contains在向量化引擎中按列批量执行且支持常量折叠适合在 WHERE 条件或过滤表达式中使用对海量行的数组成员判断可配合物化视图或 BITMAP 索引等方案进一步加速。兼容迁移从 Trino 迁移的 SQL 中原有的contains(arr, e)可直接运行StarRocks 的 SQL 解析层会自动将其映射为array_contains。以上行为与实现均可在当前仓库对应源码中验证函数文档见 array_contains.mdBE 实现见 array_functions.cpp 与 array_functions.h单元测试见 array_functions_test.cpp。【免费下载链接】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），仅供参考
