RoaringBitmap constructor|V4.4.2| docs|Distributed Database

RoaringBitmap constructor

Last Updated：2026-03-06 07:02:42 Updated

The RoaringBitmap constructor is used to create new RoaringBitmap data types. OceanBase Database currently supports the rb_build(), rb_build_empty(), rb_build_varbinary(), and rb_from_string() functions for constructing RoaringBitmap data.

Note

For more information about the considerations for visualized hexadecimal query results, see Create a highly compressed RoaringBitmap column.

rb_build

The rb_build() function is used to convert array data with an integer base type into a highly compressed RoaringBitmap. Syntax:

rb_build(arr)

The input parameters are described as follows:

arr: The input parameter must be an array.

The return value is a RoaringBitmap containing all elements of the array.

Constraints:

The array cannot contain null elements.
If the array is a nested array, recursively extract the base elements of each subarray and insert them into the RoaringBitmap.
The RoaringBitmap supports inserting unsigned 64-bit integers (uint64) and signed 32-bit integers (int32) data. In the same way as the rb_from_string function, the input signed 32-bit integers will be converted to unsigned 32-bit integers before being inserted into the RoaringBitmap. Therefore, the allowed input integer range is from the minimum value of signed 32-bit integers to the maximum value of unsigned 64-bit integers, that is, [INT32_MIN, UINT64_MAX].

Examples:

SELECT rb_to_string(rb_build([1.2]));
ERROR 5083 (22000): Invalid data type for the operation

SELECT rb_to_string(rb_build([0,1,2]));
+---------------------------------+
| rb_to_string(rb_build([0,1,2])) |
+---------------------------------+
| 0,1,2                           |
+---------------------------------+
1 row in set

SELECT rb_to_string(rb_build([[0,1],[2],[2,3]]));
+-------------------------------------------+
| rb_to_string(rb_build([[0,1],[2],[2,3]])) |
+-------------------------------------------+
| 0,1,2,3                                   |
+-------------------------------------------+
1 row in set

rb_build_empty

The rb_build_empty() function is used to create an empty RoaringBitmap. Syntax:

rb_build_empty()

This function does not require any input parameters.

Examples:

SELECT rb_build_empty();
+------------------------------------+
| rb_build_empty()                   |
+------------------------------------+
| 0x0100                             |
+------------------------------------+
1 row in set

SELECT rb_is_empty(rb_build_empty());
+-------------------------------+
| rb_is_empty(rb_build_empty()) |
+-------------------------------+
|                             1 |
+-------------------------------+
1 row in set

rb_build_varbinary

The rb_build_varbinary() function is used to construct RoaringBitmap data from a varbinary string. Varbinary is a private format of OceanBase Database, consisting of parts such as version information, type information, and data. Syntax:

rb_build_varbinary(bin_str)

The input parameter is a varbinary string.

Examples:

SELECT rb_to_string(rb_build_varbinary(x'0100'));
+-------------------------------------------+
| rb_to_string(rb_build_varbinary(x'0100')) |
+-------------------------------------------+
|                                           |
+-------------------------------------------+
1 row in set

SELECT rb_to_string(rb_build_varbinary(x'0103020100000002000000'));
+-------------------------------------------------------------+
| rb_to_string(rb_build_varbinary(x'0103020100000002000000')) |
+-------------------------------------------------------------+
| 1,2                                                         |
+-------------------------------------------------------------+
1 row in set

rb_from_string

The rb_from_string() function is used to construct RoaringBitmap data from a string in a specific format. The string contains each element of the RoaringBitmap data, separated by commas, such as 1,2,3,4. Syntax:

rb_from_string(str)

The input string supports two formats: INT32 and INT64. The valid value range supported by OceanBase Database is [0, UINT64_MAX]. However, for compatibility with PostgreSQL, it also supports the input of negative integers in the range [INT32_MIN,0). During output, negative integers will be converted to UINT32 values. For example, if the input is -1, the output will be 4294967295.

Examples:

SELECT rb_from_string('1,2,3');
+--------------------------------------------------+
| rb_from_string('1,2,3')                          |
+--------------------------------------------------+
| 0x010303010000000200000003000000                 |
+--------------------------------------------------+
1 row in set

SELECT rb_to_string(rb_from_string('-1'));
+------------------------------------+
| rb_to_string(rb_from_string('-1')) |
+------------------------------------+
| 4294967295                         |
+------------------------------------+
1 row in set

rb_select

RoaringBitmap data stores a set of non-negative integers. The rb_select() function can select a subset of values from the RoaringBitmap data based on specified conditions, save them as a new RoaringBitmap, and return the value. Syntax:

res_rb = rb_select(rb, limit [, offset] [, reverse] [, range_start] [, range_end])

The parameters are described as follows:

Parameter	Data type	Default value	Description	Required
rb	RoaringBitmap		The RoaringBitmap data to be input.	Yes
limit	uint64		The maximum number of elements to output.	Yes
offset	uint64	0	The offset of the starting position for output.	No
reverse	bool	false	Whether to output in reverse order.	No
range_start	uint64	0	The start value of the output range.	No
range_end	uint64	UINT64_MAX	The end value of the output range.	No

The calculation order is as follows:

If a range is specified, filter out all elements within the range [range_start, range_end).
If reverse is false, select values in ascending order; if true, select in descending order. The rb_select() function calculates the starting position for output based on the reverse direction from the filtered elements.
Calculate offset.
Calculate limit, and output up to limit elements within the range. If there are fewer than limit elements in the range, output all elements within the range.

The return value is a RoaringBitmap.

Examples:

Return the first 3 values from the '10, 20, 30, 40, 50, 60, 70' range:

SELECT rb_to_string(rb_select(rb_from_string('10, 20, 30, 40, 50, 60, 70'), 3));
+--------------------------------------------------------------------------+
| rb_to_string(rb_select(rb_from_string('10, 20, 30, 40, 50, 60, 70'), 3)) |
+--------------------------------------------------------------------------+
| 10,20,30                                                                 |
+--------------------------------------------------------------------------+
1 row in set

Offset by 2 and return the first 2 values from the '1,2,3,4,5,6,7' range:

SELECT rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 2));
+----------------------------------------------------------------+
| rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 2)) |
+----------------------------------------------------------------+
| 3,4                                                            |
+----------------------------------------------------------------+
1 row in set

Select the first 2 values in ascending order from the range [2, 6):

SELECT rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 0, false, 2, 6));
+-----------------------------------------------------------------------------+
| rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 0, false, 2, 6)) |
+-----------------------------------------------------------------------------+
| 2,3                                                                         |
+-----------------------------------------------------------------------------+
1 row in set

On the basis of the range [2, 6), calculate the result by offsetting in reverse order by 1 and return the first 2 values:

SELECT rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 1, true, 2, 6));
+----------------------------------------------------------------------------+
| rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 2, 1, true, 2, 6)) |
+----------------------------------------------------------------------------+
| 3,4                                                                        |
+----------------------------------------------------------------------------+
1 row in set

On the basis of the range [2, 6), calculate the result by offsetting in ascending order by 1 and return the first 10 values (only 3 values are actually returned):

SELECT rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 10, 1, false, 2, 6));
+------------------------------------------------------------------------------+
| rb_to_string(rb_select(rb_from_string('1,2,3,4,5,6,7'), 10, 1, false, 2, 6)) |
+------------------------------------------------------------------------------+
| 3,4,5                                                                        |
+------------------------------------------------------------------------------+
1 row in set