Realtime Compute for Apache Flink:BITMAP functions

BITMAP_BUILD(array)

Creates a BITMAP from an array of 32-bit integers. Returns NULL if the input is NULL.

SELECT BITMAP_TO_STRING(BITMAP_BUILD(ARRAY[1, 2, 3, 4, 5]));
-- Result: {1,2,3,4,5}

-- NULL input returns NULL
SELECT BITMAP_BUILD(NULL);
-- Result: NULL

BITMAP_CARDINALITY(bitmap)

Returns the number of distinct elements in a bitmap as a 64-bit integer. Duplicate values are counted once. Returns NULL if the input is NULL.

SELECT BITMAP_CARDINALITY(BITMAP_BUILD(ARRAY[1, 2, 3, 3, 5]));
-- Result: 4  (3 appears twice but is counted once)

Tip: In aggregation pipelines, use BITMAP_XX_CARDINALITY_AGG() directly instead of BITMAP_CARDINALITY(BITMAP_XX_AGG()) for better performance.

BITMAP_AND(bitmap1, bitmap2)

Returns the intersection (AND) of two bitmaps — elements present in both. Returns NULL if either input is NULL.

-- Normal case
SELECT BITMAP_TO_STRING(
  BITMAP_AND(BITMAP_BUILD(ARRAY[1, 2, 3]), BITMAP_BUILD(ARRAY[2, 3, 4]))
);
-- Result: {2,3}

-- NULL input returns NULL
SELECT BITMAP_TO_STRING(
  BITMAP_AND(BITMAP_BUILD(ARRAY[1, 2, 3]), NULL)
);
-- Result: NULL

BITMAP_OR(bitmap1, bitmap2)

Returns the union (OR) of two bitmaps — all distinct elements from both. Returns NULL if either input is NULL.

-- Normal case
SELECT BITMAP_TO_STRING(
  BITMAP_OR(BITMAP_BUILD(ARRAY[1, 2, 3]), BITMAP_BUILD(ARRAY[3, 4, 5]))
);
-- Result: {1,2,3,4,5}

-- NULL input returns NULL
SELECT BITMAP_TO_STRING(
  BITMAP_OR(BITMAP_BUILD(ARRAY[1, 2, 3]), NULL)
);
-- Result: NULL

BITMAP_XOR(bitmap1, bitmap2)

Returns the exclusive OR (XOR) of two bitmaps — elements in either bitmap but not both. Returns NULL if either input is NULL.

SELECT BITMAP_TO_STRING(
  BITMAP_XOR(BITMAP_BUILD(ARRAY[1, 2, 3]), BITMAP_BUILD(ARRAY[2, 3, 4]))
);
-- Result: {1,4}

BITMAP_ANDNOT(bitmap1, bitmap2)

Returns the difference (AND NOT) of two bitmaps — elements in bitmap1 that are not in bitmap2. Returns NULL if either input is NULL.

SELECT BITMAP_TO_STRING(
  BITMAP_ANDNOT(BITMAP_BUILD(ARRAY[1, 2, 3]), BITMAP_BUILD(ARRAY[2, 3, 4]))
);
-- Result: {1}

BITMAP_FROM_BYTES(bytes)

Deserializes a byte array into a BITMAP. The byte array must follow the 32-bit RoaringBitmap format specification. Use this function to import bitmaps produced by external systems. Returns NULL if the input is NULL.

BITMAP_TO_BYTES(bitmap)

Serializes a BITMAP into a byte array following the 32-bit RoaringBitmap format specification. Use this function to export bitmaps to external systems that support RoaringBitmap. Returns NULL if the input is NULL.

BITMAP_TO_ARRAY(bitmap)

Converts a BITMAP into an ARRAY<INT>. Values are sorted by Integer.compareUnsigned. Returns NULL if the input is NULL.

SELECT BITMAP_TO_ARRAY(BITMAP_BUILD(ARRAY[3, 1, 2]));
-- Result: [1, 2, 3]  (sorted by Integer.compareUnsigned)

BITMAP_TO_STRING(bitmap)

Converts a BITMAP into a comma-separated string enclosed in curly braces. Values are sorted by Integer.compareUnsigned. If the resulting string is too long, it is truncated and ends with .... Returns NULL if the input is NULL.

Output examples:

BITMAP stores 32-bit unsigned integers. Values that appear negative as signed 32-bit integers (such as -1 and -2) are represented as their unsigned equivalents (4294967295 and 4294967294) in the output.