RoaringBitmap Functions for High-Performance Bitmap Analytics - MaxCompute

RoaringBitmap is an efficient bitmap compression algorithm widely used in big data platforms. MaxCompute supports RoaringBitmap functions for deduplication, tag filtering, and time series data processing on ultra-high-dimensional datasets.

How it works

RoaringBitmap stores integers in typed containers and selects the most compact container type automatically:

32-bit integers: up to 2^16 containers. The 16 most significant bits identify the container; the 16 least significant bits are stored in that container.
64-bit integers: up to 2^32 containers. The 32 most significant bits identify the container in a first-level index; the 32 least significant bits are stored in that container.
Container types: array containers, bitmap containers, and run containers.

MaxCompute implements RoaringBitmap32 for 32-bit integers and RoaringBitmap64 for 64-bit integers. You do not need to distinguish between them — the type is inferred automatically from your input.

This storage structure enables rapid value retrieval and efficient bitwise operations (AND, OR, XOR) across containers.

Limits

Constraint	Details
Required session flag	Set `set odps.sql.type.system.odps2=true;` before running any query that uses RoaringBitmap functions. Without this flag, queries fail with `Semantic analysis exception - function or view xxx cannot be resolved`.
No RoaringBitmap table columns	You cannot create a table with RoaringBitmap-typed columns. Serialize bitmap data with `RB_SERIALIZE` and store it as BINARY. Deserialize it back with `RB_DESERIALIZE` when you need to use it.
No direct bitmap output	Functions that return a RoaringBitmap cannot be displayed directly — the query fails. Wrap the result in `RB_TO_ARRAY` to convert it to an integer array for display. Example: `SELECT rb_to_array(rb_build(array(1, 2, 2)));` returns `[1, 2]`.

Aggregate functions

Aggregate functions operate on a column of values and produce a single bitmap or scalar result.

Function	Description
RB_BUILD_AGG	Aggregates an INT or BIGINT column into a single RoaringBitmap.
RB_CARDINALITY_AGG	Returns the count of distinct values in an INT or BIGINT column. Equivalent to `COUNT(DISTINCT col)`.
RB_AND_AGG	Returns the intersection of all RoaringBitmap values in a column — elements present in every row.
RB_OR_AGG	Returns the union of all RoaringBitmap values in a column — all elements across all rows.
RB_XOR_AGG	Returns elements that appear in an odd number of rows (XOR across all rows).
RB_AND_CARDINALITY_AGG	Returns the cardinality of the intersection of all RoaringBitmap values in a column.
RB_OR_CARDINALITY_AGG	Returns the cardinality of the union of all RoaringBitmap values in a column.
RB_XOR_CARDINALITY_AGG	Returns the cardinality of the XOR result of all RoaringBitmap values in a column.

Sample data

The examples in this section use the following table:

DROP TABLE IF EXISTS t_test;
CREATE TABLE t_test
(
    col_int    INT,
    col_bigint BIGINT
);

INSERT INTO t_test VALUES(1,1),(2,2),(1,2);

RB_BUILD_AGG

Syntax

roaringbitmap rb_build_agg(int|bigint col)

Description

Aggregates all values in an INT or BIGINT column into a single RoaringBitmap, deduplicating as it goes.

INT input → RoaringBitmap32
BIGINT input → RoaringBitmap64

Parameters

Parameter	Type	Description
`col`	INT or BIGINT	Column to aggregate. Required.

Return value

RoaringBitmap — all distinct values in the column.

Examples

-- INT column
SELECT rb_to_array(rb_build_agg(col_int)) FROM t_test;

Result: [1, 2]

-- BIGINT column
SELECT rb_to_array(rb_build_agg(col_bigint)) FROM t_test;

Result: [1, 2]

RB_CARDINALITY_AGG

Syntax

bigint rb_cardinality_agg(int|bigint col)

Description

Returns the count of distinct values in an INT or BIGINT column. Equivalent to COUNT(DISTINCT col) but uses RoaringBitmap internally.

Parameters

Parameter	Type	Description
`col`	INT or BIGINT	Column to count distinct values from. Required.

Return value

BIGINT — the number of distinct values.

Examples

SELECT rb_cardinality_agg(col_int) FROM t_test;

Result: 2

SELECT rb_cardinality_agg(col_bigint) FROM t_test;

Result: 2

RB_AND_AGG

Syntax

roaringbitmap rb_and_agg(roaringbitmap col)

Description

Returns the intersection of all RoaringBitmap values in a column — the elements that appear in every row.

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to intersect. Required.

Return value

RoaringBitmap — elements present in all rows.

Examples

SELECT rb_to_array(rb_and_agg(rb_build(array(col_int)))) FROM t_test;

Result: [] (no value appears in all three rows)

SELECT rb_to_array(rb_and_agg(rb_build(array(col_bigint)))) FROM t_test;

Result: []

RB_OR_AGG

Syntax

roaringbitmap rb_or_agg(roaringbitmap col)

Description

Returns the union of all RoaringBitmap values in a column — all elements across all rows.

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to union. Required.

Return value

RoaringBitmap — all elements present in any row.

Examples

SELECT rb_to_array(rb_or_agg(rb_build(array(col_int)))) FROM t_test;

Result: [1, 2]

SELECT rb_to_array(rb_or_agg(rb_build(array(col_bigint)))) FROM t_test;

Result: [1, 2]

RB_XOR_AGG

Syntax

roaringbitmap rb_xor_agg(roaringbitmap col)

Description

Returns elements that appear in an odd number of rows across all RoaringBitmap values in the column (XOR aggregation).

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to XOR. Required.

Return value

RoaringBitmap — elements that appear in an odd number of rows.

Examples

SELECT rb_to_array(rb_xor_agg(rb_build(array(col_int)))) FROM t_test;

Result: [2]

SELECT rb_to_array(rb_xor_agg(rb_build(array(col_bigint)))) FROM t_test;

Result: [1]

RB_AND_CARDINALITY_AGG

Syntax

bigint rb_and_cardinality_agg(roaringbitmap col)

Description

Returns the cardinality of the intersection of all RoaringBitmap values in a column.

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to intersect. Required.

Return value

BIGINT — number of elements present in every row.

Examples

SELECT rb_and_cardinality_agg(rb_build(array(col_int))) FROM t_test;

Result: 0

SELECT rb_and_cardinality_agg(rb_build(array(col_bigint))) FROM t_test;

Result: 0

RB_OR_CARDINALITY_AGG

Syntax

bigint rb_or_cardinality_agg(roaringbitmap col)

Description

Returns the cardinality of the union of all RoaringBitmap values in a column.

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to union. Required.

Return value

BIGINT — total number of distinct elements across all rows.

Examples

SELECT rb_or_cardinality_agg(rb_build(array(col_int))) FROM t_test;

Result: 2

SELECT rb_or_cardinality_agg(rb_build(array(col_bigint))) FROM t_test;

Result: 2

RB_XOR_CARDINALITY_AGG

Syntax

bigint rb_xor_cardinality_agg(roaringbitmap col)

Description

Returns the cardinality of the XOR result of all RoaringBitmap values in a column.

Parameters

Parameter	Type	Description
`col`	RoaringBitmap	Column to XOR. Required.

Return value

BIGINT — number of elements that appear in an odd number of rows.

Examples

SELECT rb_xor_cardinality_agg(rb_build(array(col_int))) FROM t_test;

Result: 1

SELECT rb_xor_cardinality_agg(rb_build(array(col_bigint))) FROM t_test;

Result: 1

Functions

Non-aggregate (scalar) functions operate on individual RoaringBitmap values.

Function	Description
RB_BUILD	Converts an integer array into a RoaringBitmap.
RB_TO_ARRAY	Converts a RoaringBitmap into a sorted integer array.
RB_CARDINALITY	Returns the number of distinct elements in a RoaringBitmap.
RB_AND	Returns the intersection of two RoaringBitmaps.
RB_OR	Returns the union of two RoaringBitmaps.
RB_XOR	Returns the symmetric difference of two RoaringBitmaps.
RB_ANDNOT	Returns the difference of two RoaringBitmaps (elements in `a` but not in `b`).
RB_AND_CARDINALITY	Returns the cardinality of the intersection of two RoaringBitmaps.
RB_OR_CARDINALITY	Returns the cardinality of the union of two RoaringBitmaps.
RB_XOR_CARDINALITY	Returns the cardinality of the symmetric difference of two RoaringBitmaps.
RB_ANDNOT_CARDINALITY	Returns the cardinality of the difference of two RoaringBitmaps.
RB_EQUAL	Returns true if two RoaringBitmaps contain identical elements.
RB_NOT_EQUAL	Returns true if two RoaringBitmaps differ.
RB_CONTAINS	Returns true if the first RoaringBitmap is a superset of the second.
RB_INTERSECT	Returns true if two RoaringBitmaps share at least one element.
RB_IS_EMPTY	Returns true if a RoaringBitmap contains no elements.
RB_MAXIMUM	Returns the largest element in a RoaringBitmap.
RB_MINIMUM	Returns the smallest element in a RoaringBitmap.
RB_RANGE	Returns a new RoaringBitmap containing only elements in `[start, end)`.
RB_RANGE_CARDINALITY	Returns the count of elements in the `[start, end)` range of a RoaringBitmap.
RB_FILL	Returns a new RoaringBitmap with all integers in `[start, end)` added.
RB_CLEAR	Returns a new RoaringBitmap with all integers in `[start, end)` removed.
RB_SERIALIZE	Serializes a RoaringBitmap to BINARY for storage.
RB_DESERIALIZE	Deserializes BINARY data into a RoaringBitmap64.
RB_DESERIALIZE_32	Deserializes BINARY data into a RoaringBitmap32.

RB_BUILD

Syntax

roaringbitmap rb_build(array<int|bigint> a)

Description

Converts an integer array into a RoaringBitmap. Duplicate values are deduplicated automatically.

ARRAY\<INT\> input → RoaringBitmap32
ARRAY\<BIGINT\> input → RoaringBitmap64

Parameters

Parameter	Type	Description
`a`	ARRAY\<INT\> or ARRAY\<BIGINT\>	Integer array to convert. Required. Cannot be empty.

Return value

RoaringBitmap — all distinct elements from the input array.

Examples

-- RoaringBitmap32 (INT array)
SELECT rb_to_array(rb_build(array(1, 2, 2)));

Result: [1, 2]

-- RoaringBitmap64 (BIGINT array, note the L suffix)
SELECT rb_to_array(rb_build(array(1L, 2L, 2L)));

Result: [1, 2]

RB_TO_ARRAY

Syntax

array<int|bigint> rb_to_array(roaringbitmap a)

Description

Converts a RoaringBitmap into a sorted integer array in ascending order. Use this function to display bitmap results, since RoaringBitmap values cannot be output directly.

RoaringBitmap32 → ARRAY\<INT\>
RoaringBitmap64 → ARRAY\<BIGINT\>

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to convert. Required.

Return value

ARRAY\<INT\> or ARRAY\<BIGINT\> — elements sorted in ascending order.

Example

SELECT rb_to_array(rb_build(array(1, 2, 2)));

Result: [1, 2]

RB_CARDINALITY

Syntax

bigint rb_cardinality(roaringbitmap a)

Description

Returns the number of distinct elements in a RoaringBitmap.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to count. Required.

Return value

BIGINT — element count.

Examples

SELECT rb_cardinality(rb_build(array(1, 2, 2)));

Result: 2

SELECT rb_cardinality(rb_build(array(1L, 2L, 3L)));

Result: 3

RB_AND

Syntax

roaringbitmap rb_and(roaringbitmap a, roaringbitmap b)

Description

Returns the intersection of two RoaringBitmaps — elements present in both a and b. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_and_null2empty.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

RoaringBitmap — elements in both bitmaps, or NULL if either input is NULL.

Example

SELECT rb_to_array(rb_and(rb_build(array(1, 2)), rb_build(array(2, 3))));

Result: [2]

RB_OR

Syntax

roaringbitmap rb_or(roaringbitmap a, roaringbitmap b)

Description

Returns the union of two RoaringBitmaps — all elements in a or b. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_or_null2empty.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

RoaringBitmap — all elements from both bitmaps, or NULL if either input is NULL.

Examples

SELECT rb_to_array(rb_or(rb_build(array(1, 2)), rb_build(array(2, 3))));

Result: [1, 2, 3]

SELECT rb_to_array(rb_or(rb_build(array(1L, 2L)), rb_build(array(2L, 3L))));

Result: [1, 2, 3]

RB_XOR

Syntax

roaringbitmap rb_xor(roaringbitmap a, roaringbitmap b)

Description

Returns the symmetric difference of two RoaringBitmaps — elements in a or b but not both. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_xor_null2empty.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

RoaringBitmap — elements exclusive to one bitmap, or NULL if either input is NULL.

Examples

SELECT rb_to_array(rb_xor(rb_build(array(1, 2)), rb_build(array(2, 3))));

Result: [1, 3]

SELECT rb_to_array(rb_xor(rb_build(array(1L, 2L)), rb_build(array(2L, 3L))));

Result: [1, 3]

RB_ANDNOT

Syntax

roaringbitmap rb_andnot(roaringbitmap a, roaringbitmap b)

Description

Returns the difference of two RoaringBitmaps — elements in a that are not in b. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_andnot_null2empty.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to subtract from. Required.
`b`	RoaringBitmap	Bitmap whose elements are excluded. Required.

Return value

RoaringBitmap — elements in a but not in b, or NULL if either input is NULL.

Examples

SELECT rb_to_array(rb_andnot(rb_build(array(1, 2)), rb_build(array(2, 3))));

Result: [1]

SELECT rb_to_array(rb_andnot(rb_build(array(1L, 2L)), rb_build(array(2L, 3L))));

Result: [1]

RB_AND_CARDINALITY

Syntax

bigint rb_and_cardinality(roaringbitmap a, roaringbitmap b)

Description

Returns the cardinality of the intersection of two RoaringBitmaps. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_and_null2empty_cardinality.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BIGINT — number of elements in the intersection, or NULL if either input is NULL.

Examples

SELECT rb_and_cardinality(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: 1

SELECT rb_and_cardinality(rb_build(array(1L, 2L)), rb_build(array(2L, 3L)));

Result: 1

RB_OR_CARDINALITY

Syntax

bigint rb_or_cardinality(roaringbitmap a, roaringbitmap b)

Description

Returns the cardinality of the union of two RoaringBitmaps. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_or_null2empty_cardinality.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BIGINT — number of distinct elements across both bitmaps, or NULL if either input is NULL.

Examples

SELECT rb_or_cardinality(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: 3

SELECT rb_or_cardinality(rb_build(array(1L, 2L)), rb_build(array(2L, 3L)));

Result: 3

RB_XOR_CARDINALITY

Syntax

bigint rb_xor_cardinality(roaringbitmap a, roaringbitmap b)

Description

Returns the cardinality of the symmetric difference of two RoaringBitmaps. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_xor_null2empty_cardinality.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BIGINT — number of elements exclusive to one bitmap, or NULL if either input is NULL.

Examples

SELECT rb_xor_cardinality(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: 2

SELECT rb_xor_cardinality(rb_build(array(1L, 2L)), rb_build(array(2L, 3L)));

Result: 2

RB_ANDNOT_CARDINALITY

Syntax

bigint rb_andnot_cardinality(roaringbitmap a, roaringbitmap b)

Description

Returns the cardinality of the difference of two RoaringBitmaps — elements in a but not in b. Returns NULL if either input is NULL. To treat NULL as an empty set instead, use rb_andnot_null2empty_cardinality.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to subtract from. Required.
`b`	RoaringBitmap	Bitmap whose elements are excluded. Required.

Return value

BIGINT — number of elements in a but not in b, or NULL if either input is NULL.

Examples

SELECT rb_andnot_cardinality(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: 1

SELECT rb_andnot_cardinality(rb_build(array(1L, 2L)), rb_build(array(2L, 3L)));

Result: 1

RB_EQUAL

Syntax

bool rb_equal(roaringbitmap a, roaringbitmap b)

Description

Returns true if two RoaringBitmaps contain identical elements.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BOOLEAN.

Examples

SELECT rb_equal(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: false

SELECT rb_equal(rb_build(array(1, 2)), rb_build(array(2, 1)));

Result: true

RB_NOT_EQUAL

Syntax

bool rb_not_equal(roaringbitmap a, roaringbitmap b)

Description

Returns true if two RoaringBitmaps differ.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BOOLEAN.

Examples

SELECT rb_not_equal(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: true

SELECT rb_not_equal(rb_build(array(1, 2)), rb_build(array(2, 1)));

Result: false

RB_CONTAINS

Syntax

bool rb_contains(roaringbitmap a, roaringbitmap b)

Description

Returns true if a is a superset of b — every element in b also exists in a.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to check against. Required.
`b`	RoaringBitmap	Bitmap to check for containment. Required.

Return value

BOOLEAN.

Examples

SELECT rb_contains(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: false

SELECT rb_contains(rb_build(array(1, 2, 3)), rb_build(array(1, 2)));

Result: true

RB_INTERSECT

Syntax

bool rb_intersect(roaringbitmap a, roaringbitmap b)

Description

Returns true if two RoaringBitmaps share at least one element.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	First bitmap. Required.
`b`	RoaringBitmap	Second bitmap. Required.

Return value

BOOLEAN.

Examples

SELECT rb_intersect(rb_build(array(1, 2)), rb_build(array(2, 3)));

Result: true

SELECT rb_intersect(rb_build(array(1, 2)), rb_build(array(3, 4)));

Result: false

RB_IS_EMPTY

Syntax

bool rb_is_empty(roaringbitmap a)

Description

Returns true if a RoaringBitmap contains no elements.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to check. Required.

Return value

BOOLEAN.

Examples

SELECT rb_is_empty(rb_build(array(0, 1, 2)));

Result: false

-- Check whether two non-overlapping bitmaps have an empty intersection
SELECT rb_is_empty(rb_and(rb_build(array(0, 1, 2)), rb_build(array(3, 4, 5))));

Result: true

RB_MAXIMUM

Syntax

int|bigint rb_maximum(roaringbitmap a)

Description

Returns the largest element in a RoaringBitmap.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to query. Required.

Return value

INT (for RoaringBitmap32) or BIGINT (for RoaringBitmap64).

Example

SELECT rb_maximum(rb_build(array(-1, 0, 1, 2)));

Result: 2

RB_MINIMUM

Syntax

int|bigint rb_minimum(roaringbitmap a)

Description

Returns the smallest element in a RoaringBitmap.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to query. Required.

Return value

INT (for RoaringBitmap32) or BIGINT (for RoaringBitmap64).

Example

SELECT rb_minimum(rb_build(array(-1, 0, 1, 2)));

Result: -1

RB_RANGE

Syntax

roaringbitmap rb_range(roaringbitmap a, bigint start, bigint end)

Description

Returns a new RoaringBitmap containing only elements from a that fall in the half-open interval [start, end).

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Source bitmap. Required.
`start`	BIGINT	Inclusive lower bound. Required.
`end`	BIGINT	Exclusive upper bound. Required.

Return value

RoaringBitmap — elements within [start, end).

Examples

SELECT rb_to_array(rb_range(rb_build(array(-1, 0, 1, 2)), 0L, 2L));

Result: [0, 1]

SELECT rb_to_array(rb_range(rb_build(array(-1, 0, 1, 2)), 3L, 5L));

Result: []

RB_RANGE_CARDINALITY

Syntax

bigint rb_range_cardinality(roaringbitmap a, bigint start, bigint end)

Description

Returns the count of elements in a that fall in the half-open interval [start, end).

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Source bitmap. Required.
`start`	BIGINT	Inclusive lower bound. Required.
`end`	BIGINT	Exclusive upper bound. Required.

Return value

BIGINT — element count within [start, end).

Examples

SELECT rb_range_cardinality(rb_build(array(-1, 0, 1, 2)), 0L, 2L);

Result: 2

SELECT rb_range_cardinality(rb_build(array(-1, 0, 1, 2)), 3L, 5L);

Result: 0

RB_FILL

Syntax

roaringbitmap rb_fill(roaringbitmap a, bigint start, bigint end)

Description

Returns a new RoaringBitmap with all integers in [start, end) added to a. Existing elements are preserved; elements already present are not duplicated.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Source bitmap. Required.
`start`	BIGINT	Inclusive lower bound of the range to add. Required.
`end`	BIGINT	Exclusive upper bound of the range to add. Required.

Return value

RoaringBitmap — original bitmap with the range [start, end) merged in.

Examples

-- Range [0, 2) already covered; result unchanged
SELECT rb_to_array(rb_fill(rb_build(array(-1, 0, 1, 2)), 0L, 2L));

Result: [-1, 0, 1, 2]

-- Range [3, 5) adds 3 and 4
SELECT rb_to_array(rb_fill(rb_build(array(-1, 0, 1, 2)), 3L, 5L));

Result: [-1, 0, 1, 2, 3, 4]

RB_CLEAR

Syntax

roaringbitmap rb_clear(roaringbitmap a, bigint start, bigint end)

Description

Returns a new RoaringBitmap with all integers in [start, end) removed from a. Elements outside the range are preserved.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Source bitmap. Required.
`start`	BIGINT	Inclusive lower bound of the range to remove. Required.
`end`	BIGINT	Exclusive upper bound of the range to remove. Required.

Return value

RoaringBitmap — original bitmap with the range [start, end) removed.

Examples

-- Remove [0, 2): removes 0 and 1
SELECT rb_to_array(rb_clear(rb_build(array(-1, 0, 1, 2)), 0L, 2L));

Result: [-1, 2]

-- Remove [3, 5): nothing in range; result unchanged
SELECT rb_to_array(rb_clear(rb_build(array(-1, 0, 1, 2)), 3L, 5L));

Result: [-1, 0, 1, 2]

RB_SERIALIZE

Syntax

binary rb_serialize(roaringbitmap a)

Description

Serializes a RoaringBitmap into BINARY for storage. Use this function to store RoaringBitmap data in a table — store the result as a BINARY column and deserialize it with RB_DESERIALIZE or RB_DESERIALIZE_32 when you need to use it.

Parameters

Parameter	Type	Description
`a`	RoaringBitmap	Bitmap to serialize. Required.

Return value

BINARY — serialized bitmap data.

Example

SELECT rb_serialize(rb_build(array(1L, 2L, 3L)));

RB_DESERIALIZE

Syntax

roaringbitmap64 rb_deserialize(binary a)

Description

Deserializes BINARY data into a RoaringBitmap64. Use this to read bitmaps stored as BINARY (serialized with RB_SERIALIZE).

Parameters

Parameter	Type	Description
`a`	BINARY	Serialized bitmap data. Required.

Return value

RoaringBitmap64.

Example

SELECT rb_to_array(rb_deserialize(rb_serialize(rb_build(array(1L, 2L, 3L)))));

Result: [1, 2, 3]

RB_DESERIALIZE_32

Syntax

roaringbitmap32 rb_deserialize_32(binary a)

Description

Deserializes BINARY data into a RoaringBitmap32. Use this to read 32-bit bitmaps stored as BINARY (serialized with RB_SERIALIZE).

Parameters

Parameter	Type	Description
`a`	BINARY	Serialized bitmap data. Required.

Return value

RoaringBitmap32.

Example

SELECT rb_to_array(rb_deserialize_32(rb_serialize(rb_build(array(1, 2, 3)))));

Result: [1, 2, 3]

NULL-handling variants

For RB_AND, RB_OR, RB_XOR, and RB_ANDNOT (and their _CARDINALITY counterparts), the default behavior is to return NULL when either input is NULL.

Each function has a _null2empty variant that treats NULL as an empty set instead. This is useful when NULLs in your data represent "no bitmap yet" rather than "unknown."

Default function	NULL-as-empty variant
`rb_and`	`rb_and_null2empty`
`rb_or`	`rb_or_null2empty`
`rb_xor`	`rb_xor_null2empty`
`rb_andnot`	`rb_andnot_null2empty`
`rb_and_cardinality`	`rb_and_null2empty_cardinality`
`rb_or_cardinality`	`rb_or_null2empty_cardinality`
`rb_xor_cardinality`	`rb_xor_null2empty_cardinality`
`rb_andnot_cardinality`	`rb_andnot_null2empty_cardinality`

The _null2empty variants accept the same parameters and return the same types as their default counterparts.