RoaringBitmap constructor|V4.6.0|OceanBase Database| docs|Distributed Database

RoaringBitmap constructor

Last Updated：2026-05-07 11:26:25 Updated

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

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 converts array data of the integer 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 that contains all the elements of the array.

Constraints:

The array must not contain empty elements.
If the array is a nested array, the function recursively extracts the base elements from each subarray and inserts them into the RoaringBitmap.
The RoaringBitmap supports inserting unsigned 64-bit integers (uint64) and signed 32-bit integers (int32). Similar to the behavior of rb_from_string, the function converts the input signed 32-bit integers to unsigned 32-bit integers before inserting them into the RoaringBitmap. Therefore, the input integers can range from the minimum value of a signed 32-bit integer to the maximum value of an unsigned 64-bit integer, that is, [INT32_MIN, UINT64_MAX].

Here are some 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 constructs an empty RoaringBitmap. Syntax:

rb_build_empty()

This function does not require any input parameters.

Here are some 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 constructs a RoaringBitmap from a varbinary string. Varbinary is a proprietary format of OceanBase Database, which is a binary format composed of version information, type information, and data. Syntax:

rb_build_varbinary(bin_str)

The input parameter is a varbinary string.

Here are some 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 constructs a RoaringBitmap from a string in a specific format. The string contains the elements of the RoaringBitmap, separated by commas, such as 1,2,3,4. Syntax:

rb_from_string(str)

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

Here are some 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

The RoaringBitmap stores a set of non-negative integers. The rb_select() function selects a local range of values from the RoaringBitmap based on the specified conditions, saves the selected values as a new RoaringBitmap, and returns the new RoaringBitmap. 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 to be processed.	Yes
limit	uint64		The maximum number of elements to be returned.	Yes
offset	uint64	0	The offset of the starting position.	No
reverse	bool	false	Whether to return the elements 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 process is as follows:

If a range is specified, filter out all elements in the range [range_start, range_end).
If reverse is false, the elements are returned in ascending order; if true, the elements are returned in descending order. The rb_select() function calculates the starting position of the output based on the direction specified by reverse.
Calculate offset.
Calculate limit. The function returns up to limit elements in the specified range. If the number of elements in the range is less than limit, all elements in the range are returned.

The return value is a RoaringBitmap.

Here are some examples:

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

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

Return the first two values from the range '1,2,3,4,5,6,7' after skipping two values:

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

Return the first two 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

Return the first two values in ascending order from the range [2, 6) after skipping one value in reverse order:

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

Return the first 10 values in ascending order from the range [2, 6) after skipping one value. However, only three values are 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

OceanBase

Customer Stories

Documentation

RoaringBitmap constructor

Note

rb_build

rb_build_empty

rb_build_varbinary

rb_from_string

rb_select