RB64_TO_BITMAP 函数

rb64_to_bitmap(expr)

简介

RB64_TO_BITMAP 函数用于将标准 Roaring Bitmap 64 位序列化格式的二进制数据转换为 CZ 内部的 BITMAP 类型。该函数主要用于与外部系统进行数据互通，支持 CZ BITMAP 的完整值范围，适用于包含超出 32 位无符号整数范围值的场景。

语法

rb64_to_bitmap(expr)

参数说明

• expr：BINARY 类型的表达式，包含 Roaring Bitmap 64 位序列化格式的二进制数据。

返回结果

返回 BITMAP 类型。如果输入数据不是合法的 Roaring Bitmap 64 位格式，则返回 NULL。

使用示例

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

   SELECT rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 2, 3))));
   +--------------------------------------------------------------+
   | rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 2, 3)))) |
   +--------------------------------------------------------------+
   | [1,2,3]                                                      |
   +--------------------------------------------------------------+
   

2. 支持超出 32 位范围的值（大于 4294967295）的往返转换：

   SELECT rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 4294967296, 4294967297))));
   +-------------------------------------------------------------------------------+
   | rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 4294967296, 4294967297)))) |
   +-------------------------------------------------------------------------------+
   | [1,4294967296,4294967297]                                                      |
   +-------------------------------------------------------------------------------+
   

3. 对转换结果使用 bitmap 函数进行分析：

   SELECT bitmap_count(rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 12, 123, 1234, 12345)))));
   +--------------------------------------------------------------------------------------------+
   | bitmap_count(rb64_to_bitmap(bitmap_to_rb64(bitmap_build(array(1, 12, 123, 1234, 12345))))) |
   +--------------------------------------------------------------------------------------------+
   | 5                                                                                          |
   +--------------------------------------------------------------------------------------------+
   

注意事项

• 当输入参数为 NULL 时，返回结果为 NULL。
• 当输入的二进制数据不是合法的 Roaring Bitmap 64 位序列化格式时，返回 NULL 而非报错。
• Roaring Bitmap 64 位格式支持 CZ BITMAP 的完整值范围，不受 32 位无符号整数范围（0 ~ 4294967295）的限制。对于包含超出 32 位范围值的 BITMAP 数据互通场景，应优先使用 64 位格式（rb64_to_bitmap / bitmap_to_rb64）。
• 该函数的逆操作为 bitmap_to_rb64，用于将 CZ BITMAP 转换为 Roaring Bitmap 64 位序列化格式。