BITMAP_TO_RB32 函数

bitmap_to_rb32(expr)

简介

BITMAP_TO_RB32 函数用于将 CZ 内部的 BITMAP 类型转换为标准 Roaring Bitmap 32 位序列化格式的二进制数据。该函数主要用于与外部系统（如 ClickHouse、Druid 等使用标准 Roaring Bitmap 格式的系统）进行数据导出和互通。

语法

bitmap_to_rb32(expr)

参数说明

• expr：BITMAP 类型的表达式，包含 CZ 内部 BITMAP 数据。

返回结果

返回 BINARY 类型，内容为 Roaring Bitmap 32 位序列化格式的二进制数据。如果 BITMAP 中包含超出 32 位无符号整数范围（大于 4294967295）的值，则返回 NULL。

使用示例

1. 与 rb32_to_bitmap 配合实现 BITMAP 与 Roaring Bitmap 32 位格式的往返转换：

   SELECT rb32_to_bitmap(bitmap_to_rb32(bitmap_build(array(1, 2, 3))));
   +--------------------------------------------------------------+
   | rb32_to_bitmap(bitmap_to_rb32(bitmap_build(array(1, 2, 3)))) |
   +--------------------------------------------------------------+
   | [1,2,3]                                                      |
   +--------------------------------------------------------------+
   

2. 使用 base64 编码查看转换后的二进制数据：

   SELECT base64(bitmap_to_rb32(bitmap_build(array(1, 2, 3, 4))));
   +---------------------------------------------------------+
   | base64(bitmap_to_rb32(bitmap_build(array(1, 2, 3, 4)))) |
   +---------------------------------------------------------+
   | OjAAAAEAAAAAAAMAEAAAAAEAAgADAAQA                        |
   +---------------------------------------------------------+
   

3. 当 BITMAP 包含超出 32 位范围的值时返回 NULL：

   SELECT bitmap_to_rb32(bitmap_build(array(1, 4294967296, 4294967297)));
   +---------------------------------------------------------------+
   | bitmap_to_rb32(bitmap_build(array(1, 4294967296, 4294967297))) |
   +---------------------------------------------------------------+
   | NULL                                                          |
   +---------------------------------------------------------------+
   

注意事项

• 当输入参数为 NULL 时，返回结果为 NULL。
• Roaring Bitmap 32 位格式仅支持 32 位无符号整数范围（0 ~ 4294967295）内的值。如果 CZ BITMAP 中包含超出此范围的值，函数返回 NULL。对于包含超出 32 位范围值的 BITMAP，请使用 bitmap_to_rb64 进行 64 位格式的转换。
• 该函数的逆操作为 rb32_to_bitmap，用于将 Roaring Bitmap 32 位序列化格式的二进制数据转换为 CZ BITMAP。