StarRocks `bitmap_to_array` 函数详解：BITMAP 转 BIGINT 数组的用法与底层实现

StarRocksbitmap_to_array函数详解BITMAP 转 BIGINT 数组的用法与底层实现【免费下载链接】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/starrocksbitmap_to_array是 StarRocks 提供的位图BITMAP与数组ARRAY之间的转换函数用于把 BITMAP 类型的数据展开为 BIGINT 数组是后续配合unnest等表函数做行转列、或直接消费位图明细数据的关键入口。本文以官方 SQL 参考文档为主线结合 StarRocks 仓库中 FE/BE 的源码实现与配置项完整讲解该函数的语法、参数、返回值、示例以及其在底层是如何构建 Array 列、如何处理 NULL 与超大基数等细节帮助你在实际查询中正确、高效地使用它。函数概述bitmap_to_array将一个 BITMAP 值转换为一个 BIGINT 类型的数组数组中的每个元素对应位图中包含的一个整数值。它属于 bitmap-functions 家族与bitmap_to_string、bitmap_from_string等函数配合可以实现位图与常规标量/集合类型之间的双向转换。该函数在 FE 端作为内置函数注册在 FunctionSet.java 中定义了public static final String BITMAP_TO_ARRAY bitmap_to_array在 BE 端则实现在 bitmap_functions.cpp 的BitmapFunctions::bitmap_to_array中并通过 bitmap_functions.h 中的DEFINE_VECTORIZED_FN(bitmap_to_array)注册为向量化函数。语法ARRAYBIGINT BITMAP_TO_ARRAY (bitmap)参数说明参数说明bitmap需要被转换为数组的 BITMAP 值可以是位图表列、bitmap_from_string/bitmap_agg等函数产出的位图表达式或任意返回 BITMAP 类型的子查询结果。返回值返回ARRAYBIGINT类型的数组其中每个元素对应该位图中包含的一个整数值。输入为NULL时返回NULL从 BE 实现看空位图会转换为空数组EMPTY分支不做任何追加偏移量保持为 0数组元素按值升序排列BitmapValue::to_array对内部SET表示会先排序见 bitmap_value.h对BITMAPRoaringBitmap表示则按其升序迭代输出。示例基础用法将字符串构造出的位图1, 7转为数组select bitmap_to_array(bitmap_from_string(1, 7)); ---------------------------------------------- | bitmap_to_array(bitmap_from_string(1, 7)) | ---------------------------------------------- | [1,7] | ----------------------------------------------NULL 输入位图为 NULL 时函数返回 NULLselect bitmap_to_array(NULL); ----------------------- | bitmap_to_array(NULL) | ----------------------- | NULL | -----------------------与表列结合假设有一张用户标签表某列user_ids为 BITMAP 类型可直接对该列执行转换SELECT bitmap_to_array(user_ids) AS id_array FROM user_tag_table;配合 unnest 做行转列将数组展开为多行是bitmap_to_array的典型下游用法。FE 侧的优化器规则 RewriteUnnestBitmapRule.java 与计划测试 TableFunctionTest.java 中都涉及对bitmap_to_array与unnest的配合处理例如SELECT id FROM user_tag_table, unnest(bitmap_to_array(user_ids)) AS t(id);底层实现原理BE 端向量化实现bitmap_to_array的核心实现在 bitmap_functions.cpp整体采用“先统计基数、再批量填充”的两遍式构建策略基数统计与容量预检遍历输入列的每一行通过lhs.value(row)-cardinality()获取每个位图的基数并累加到data_size用于预先为数组元素列reserve容量偏移量构建逐行向array_offsets追加当前偏移再调用BitmapValue::to_array把位图元素追加到Int64Column即 BIGINT 元素列中偏移量随之累加最终形成标准的 Array 列“偏移 元素”布局NULL 处理实现中分别处理了has_null()、only_null()、无 NULL 三种情况——输入列全为 NULL 时直接返回常量 NULL 列部分为 NULL 时构造可空 Array 列NULL 行在偏移数组中保持偏移不变常量折叠通过ColumnHelper::is_all_const(columns)判断在输入为常量时输出常量列避免逐行重复计算。位图内部三种表示的转换bitmap_to_array最终调用 BitmapValue::to_array。BitmapValue内部按基数采用三种存储形态转换逻辑也因此分派EMPTY空位图不追加任何元素SINGLE单值位图直接emplace_back该唯一值BITMAPRoaringBitmap 形态先resize元素列再通过toUint64Array批量输出SET小型集合形态追加后用std::sort对新增区间排序保证输出升序。大小限制配置项为防止超大位图展开导致内存暴涨转换前会通过detect_bitmap_cardinality做基数检查见 bitmap_functions.cpp当某行位图基数超过配置项max_length_for_bitmap_function时会抛出异常bitmap_to_array not supported size 1000000该配置项在 config.h 中定义默认值为1000000CONF_mInt64(max_length_for_bitmap_function, 1000000)可在 BE 配置文件be.conf中按需调整适用于所有调用该预检逻辑的 bitmap 函数。使用建议与注意事项与bitmap_from_string对称使用字符串转位图可参考 bitmap_from_string两者组合可实现位图数据在文本与数组之间的往返转换关注基数上限对基数可能超过max_length_for_bitmap_function默认 100 万的位图执行转换前应评估内存与耗时必要时在 BE 配置中调高上限并做好资源规划NULL 语义位图为 NULL 时结果为 NULL 而非空数组业务侧如需将 NULL 视为空集合可配合ifnull/coalesce处理结果排序输出数组按值升序排列若下游对顺序有强依赖可在 SQL 中显式ORDER BY确保语义稳定。小结bitmap_to_array是 StarRocks 位图生态中连接“压缩集合”与“可展开明细”的桥梁语法上只需一个 BITMAP 参数即可得到 BIGINT 数组实现上由 BE 端两遍式向量化构建 Array 列并通过max_length_for_bitmap_function提供基数保护配合unnest表函数可实现位图数据的行转列分析。理解其语法、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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考