ClickHouse/docs/en/sql-reference/functions/bitmap-functions.md

slug	sidebar_position	sidebar_label
/en/sql-reference/functions/bitmap-functions	25	Bitmap

Bitmap Functions

Bitmaps can be constructed in two ways. The first way is constructed by aggregation function groupBitmap with -State, the other way is to constructed a bitmap from an Array object.

bitmapBuild

Builds a bitmap from an unsigned integer array.

Syntax

bitmapBuild(array)

Arguments

• array – Unsigned integer array.

Example

SELECT bitmapBuild([1, 2, 3, 4, 5]) AS res, toTypeName(res);

┌─res─┬─toTypeName(bitmapBuild([1, 2, 3, 4, 5]))─────┐
│     │ AggregateFunction(groupBitmap, UInt8)        │
└─────┴──────────────────────────────────────────────┘

bitmapToArray

Converts bitmap to an integer array.

Syntax

bitmapToArray(bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapToArray(bitmapBuild([1, 2, 3, 4, 5])) AS res;

Result:

┌─res─────────┐
│ [1,2,3,4,5] │
└─────────────┘

bitmapSubsetInRange

Returns the subset of a bitmap with bits within a value interval.

Syntax

bitmapSubsetInRange(bitmap, range_start, range_end)

Arguments

• bitmap – Bitmap object.
• range_start – Start of the range (inclusive). UInt32.
• range_end – End of the range (exclusive). UInt32.

Example

SELECT bitmapToArray(bitmapSubsetInRange(bitmapBuild([0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,100,200,500]), toUInt32(30), toUInt32(200))) AS res;

Result:

┌─res───────────────┐
│ [30,31,32,33,100] │
└───────────────────┘

bitmapSubsetLimit

Returns a subset of a bitmap with smallest bit value range_start and at most cardinality_limit elements.

Syntax

bitmapSubsetLimit(bitmap, range_start, cardinality_limit)

Arguments

• bitmap – Bitmap object.
• range_start – Start of the range (inclusive). UInt32.
• cardinality_limit – Maximum cardinality of the subset. UInt32.

Example

SELECT bitmapToArray(bitmapSubsetLimit(bitmapBuild([0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,100,200,500]), toUInt32(30), toUInt32(200))) AS res;

Result:

┌─res───────────────────────┐
│ [30,31,32,33,100,200,500] │
└───────────────────────────┘

subBitmap

Returns a subset of the bitmap, starting from position offset. The maximum cardinality of the returned bitmap is cardinality_limit.

Syntax

subBitmap(bitmap, offset, cardinality_limit)

Arguments

• bitmap – The bitmap. Bitmap object.
• offset – The position of the first element of the subset. UInt32.
• cardinality_limit – The maximum number of elements in the subset. UInt32.

Example

SELECT bitmapToArray(subBitmap(bitmapBuild([0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,100,200,500]), toUInt32(10), toUInt32(10))) AS res;

Result:

┌─res─────────────────────────────┐
│ [10,11,12,13,14,15,16,17,18,19] │
└─────────────────────────────────┘

bitmapContains

Checks whether the bitmap contains an element.

bitmapContains(bitmap, needle)

Arguments

• bitmap – Bitmap object.
• needle – Searched bit value. UInt32.

Returned values

• 0 — If bitmap does not contain needle. UInt8.
• 1 — If bitmap contains needle. UInt8.

Example

SELECT bitmapContains(bitmapBuild([1,5,7,9]), toUInt32(9)) AS res;

Result:

┌─res─┐
│  1  │
└─────┘

bitmapHasAny

Checks whether two bitmaps intersect.

If bitmap2 contains exactly one element, consider using bitmapContains instead as it works more efficiently.

Syntax

bitmapHasAny(bitmap1, bitmap2)

Arguments

• bitmap1 – Bitmap object 1.
• bitmap2 – Bitmap object 2.

Return values

• 1, if bitmap1 and bitmap2 have at least one shared element.
• 0, otherwise.

Example

SELECT bitmapHasAny(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│  1  │
└─────┘

bitmapHasAll

Returns 1 if the first bitmap contains all elements of the second bitmap, otherwise 0. If the second bitmap is empty, returns 1.

Also see hasAll(array, array).

Syntax

bitmapHasAll(bitmap1, bitmap2)

Arguments

• bitmap1 – Bitmap object 1.
• bitmap2 – Bitmap object 2.

Example

SELECT bitmapHasAll(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│  0  │
└─────┘

bitmapCardinality

Returns the cardinality of a bitmap.

Syntax

bitmapCardinality(bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapCardinality(bitmapBuild([1, 2, 3, 4, 5])) AS res;

Result:

┌─res─┐
│   5 │
└─────┘

bitmapMin

Computes the smallest bit set in a bitmap, or UINT32_MAX if the bitmap is empty.

Syntax

bitmapMin(bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapMin(bitmapBuild([1, 2, 3, 4, 5])) AS res;

Result:

 ┌─res─┐
 │   1 │
 └─────┘

bitmapMax

Computes the greatest bit set in a bitmap, or 0 if the bitmap is empty.

Syntax

bitmapMax(bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapMax(bitmapBuild([1, 2, 3, 4, 5])) AS res;

Result:

 ┌─res─┐
 │   5 │
 └─────┘

bitmapTransform

Replaces at most N bits in a bitmap. The old and new value of the i-th replaced bit is given by from_array[i] and to_array[i].

The result depends on the array ordering if from_array and to_array.

Syntax

bitmapTransform(bitmap, from_array, to_array)

Arguments

• bitmap – Bitmap object.
• from_array – UInt32 array. For idx in range [0, from_array.size()), if bitmap contains from_array[idx], then replace it with to_array[idx].
• to_array – UInt32 array with the same size as from_array.

Example

SELECT bitmapToArray(bitmapTransform(bitmapBuild([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), cast([5,999,2] as Array(UInt32)), cast([2,888,20] as Array(UInt32)))) AS res;

Result:

 ┌─res───────────────────┐
 │ [1,3,4,6,7,8,9,10,20] │
 └───────────────────────┘

bitmapAnd

Computes the logical conjunction of two bitmaps.

Syntax

bitmapAnd(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapToArray(bitmapAnd(bitmapBuild([1,2,3]),bitmapBuild([3,4,5]))) AS res;

Result:

┌─res─┐
│ [3] │
└─────┘

bitmapOr

Computes the logical disjunction of two bitmaps.

Syntax

bitmapOr(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapToArray(bitmapOr(bitmapBuild([1,2,3]),bitmapBuild([3,4,5]))) AS res;

Result:

┌─res─────────┐
│ [1,2,3,4,5] │
└─────────────┘

bitmapXor

Xor-s two bitmaps.

Syntax

bitmapXor(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapToArray(bitmapXor(bitmapBuild([1,2,3]),bitmapBuild([3,4,5]))) AS res;

Result:

┌─res───────┐
│ [1,2,4,5] │
└───────────┘

bitmapAndnot

Computes the logical conjunction of two bitmaps and negates the result.

Syntax

bitmapAndnot(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapToArray(bitmapAndnot(bitmapBuild([1,2,3]),bitmapBuild([3,4,5]))) AS res;

Result:

┌─res───┐
│ [1,2] │
└───────┘

bitmapAndCardinality

Returns the cardinality of the logical conjunction of two bitmaps.

Syntax

bitmapAndCardinality(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapAndCardinality(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│   1 │
└─────┘

bitmapOrCardinality

Returns the cardinality of the logical disjunction of two bitmaps.

bitmapOrCardinality(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapOrCardinality(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│   5 │
└─────┘

bitmapXorCardinality

Returns the cardinality of the XOR of two bitmaps.

bitmapXorCardinality(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapXorCardinality(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│   4 │
└─────┘

bitmapAndnotCardinality

Returns the cardinality of the AND-NOT operation of two bitmaps.

bitmapAndnotCardinality(bitmap,bitmap)

Arguments

• bitmap – Bitmap object.

Example

SELECT bitmapAndnotCardinality(bitmapBuild([1,2,3]),bitmapBuild([3,4,5])) AS res;

Result:

┌─res─┐
│   2 │
└─────┘