RoaringBitmap constructor functions

The RoaringBitmap constructor functions are used to construct new RoaringBitmap data. The RoaringBitmap constructor functions supported by seekdb include rb_build(), rb_build_empty(), rb_build_varbinary(), and rb_from_string().

info

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

rb_build

The rb_build() function is used to convert an array of integers into a RoaringBitmap. The syntax is as follows:

rb_build(arr)

The input parameters are described as follows:

• arr specifies the array to be converted. The data type of the array must be an array.

The return value is a RoaringBitmap that contains all the elements in the array.

Constraints:

• The array must not contain null values.
• If the array is a nested array, the function recursively extracts the base elements of each subarray and inserts them into the RoaringBitmap.
• The RoaringBitmap supports inserting unsigned 64-bit integers (uint64) and signed 32-bit integers (int32). The behavior of the rb_from_string() function is consistent with this. That is, the input signed 32-bit integers are first converted to unsigned 32-bit integers and then inserted into the RoaringBitmap. Therefore, the input integers can be in the range from the minimum value of the signed 32-bit integer to the maximum value of the 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 (0.001 sec)

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 (0.001 sec)

rb_build_empty

The rb_build_empty() function is used to construct an empty RoaringBitmap. The syntax is as follows:

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 (0.001 sec)

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

rb_build_varbinary

The rb_build_varbinary() function is used to construct a RoaringBitmap from a varbinary string. Varbinary is a proprietary format of seekdb, which is a binary format that consists of version information, type information, and data. The syntax is as follows:

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 (0.001 sec)

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

rb_from_string

The rb_from_string() function is used to construct a RoaringBitmap from a string. The string contains the elements of the RoaringBitmap, which are separated by commas. The syntax is as follows:

rb_from_string(str)

The input string supports the INT32 and INT64 formats. The valid value range of the input string is [0, UINT64_MAX]. However, to ensure compatibility with PostgreSQL, the input string also supports the range [INT32_MIN, 0). In this case, the negative integers are converted to unsigned 32-bit integers before being output. 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 (0.001 sec)

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

rb_select

A RoaringBitmap stores a set of non-negative integers. The rb_select() function is used to select a subset of values from the RoaringBitmap based on the specified conditions, save the subset as a new RoaringBitmap, and return the value of the new RoaringBitmap. The syntax is as follows:

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

The parameters are described as follows:

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

The calculation process is as follows:

1. If a range is specified, all elements in the range [range_start, range_end) are filtered out.

2. If reverse is false, the elements are selected in ascending order; if reverse is true, the elements are selected in descending order. The rb_select() function calculates the starting position of the output based on the direction specified by reverse from the filtered elements.

3. Calculate offset.

4. Calculate limit. The function outputs at most limit elements in the range. If the number of elements in the range is less than limit, all elements in the range are output.

The return value is a RoaringBitmap.

Here are some examples:

Return the first three 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 (0.001 sec)

Skip the first two values and return the first two 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 (0.001 sec)

Select 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 (0.001 sec)

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

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 (0.001 sec)

Select the first 10 values in ascending order from the range [2, 6). The actual number of values returned is 3:

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 (0.001 sec)