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

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

【免费下载链接】starrocksThe world's 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

bitmap_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)注册为向量化函数。

语法

ARRAY<BIGINT> BITMAP_TO_ARRAY (bitmap)

参数说明

参数	说明
`bitmap`	需要被转换为数组的 BITMAP 值，可以是位图表列、`bitmap_from_string`/`bitmap_agg`等函数产出的位图表达式，或任意返回 BITMAP 类型的子查询结果。

返回值

返回ARRAY<BIGINT>类型的数组，其中每个元素对应该位图中包含的一个整数值。

输入为NULL时，返回NULL；
从 BE 实现看，空位图会转换为空数组（EMPTY分支不做任何追加，偏移量保持为 0）；
数组元素按值升序排列：BitmapValue::to_array对内部SET表示会先排序（见 bitmap_value.h），对BITMAP（RoaringBitmap）表示则按其升序迭代输出。

示例

基础用法

将字符串构造出的位图"1, 7"转为数组：

select bitmap_to_array(bitmap_from_string("1, 7")); +----------------------------------------------+ | bitmap_to_array(bitmap_from_string('1, 7')) | +----------------------------------------------+ | [1,7] | +----------------------------------------------+

NULL 输入

位图为 NULL 时，函数返回 NULL：

select 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该唯一值；
BITMAP：RoaringBitmap 形态，先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 中定义，默认值为1000000（CONF_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 语义、排序特性与限制项，可以帮助你在真实业务中安全、高效地使用这一转换能力。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析