Bitmap Functions

Bitmap 可通过两种方式构造。第一种是使用带有 -State 的聚合函数 groupBitmap 进行构造，另一种是从 Array 对象构造 bitmap。

bitmapAnd

首次引入于：v20.1.0 计算两个 bitmap 的逻辑与 (AND) 。语法

bitmapAnd(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回一个 bitmap，其中包含两个输入 bitmap 中都存在的位 AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

bitmapAndCardinality

引入于：v20.1.0 返回两个 bitmap 逻辑与 (AND) 结果的基数。语法

bitmapAndCardinality(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回两个 bitmap 交集中置为 1 的位数。UInt64 示例 用法示例

Query

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

Response

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

bitmapAndnot

始于版本：v20.1.0 计算两个 bitmap 的集合差集 A AND-NOT B。语法

bitmapAndnot(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回一个 bitmap，包含第一个 bitmap 中已置位但第二个 bitmap 中未置位的位 AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

bitmapAndnotCardinality

引入版本：v20.1.0 返回两个 bitmap 进行 AND-NOT 运算后结果的基数。语法

bitmapAndnotCardinality(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。- bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回 bitmap1 AND-NOT bitmap2 结果中置位的位数。UInt64 示例 使用示例

Query

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

Response

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

bitmapBuild

引入版本：v20.1.0 根据整数数组构建 bitmap。支持的元素类型为 8、16、32 或 64 位有符号和无符号整数。它是函数 bitmapToArray 的逆操作。语法

bitmapBuild(array)

参数

array — 整数数组。Array((U)Int*)

返回值 返回由给定数组构建的 bitmap AggregateFunction(groupBitmap, T) 示例 用法示例

Query

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

Response

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

有符号 bitmap

Query

SELECT bitmapBuild([-128, -1]::Array(Int8)) AS res, toTypeName(res);

Response

┌─res─┬─toTypeName(bitmapBuild([-128, -1]::Array(Int8)))─┐
│     │ AggregateFunction(groupBitmap, Int8)             │
└─────┴──────────────────────────────────────────────────┘

bitmapCardinality

引入版本：v20.1.0 返回 bitmap 中置为 1 的位数 (即基数) 。语法

bitmapCardinality(bitmap)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回 bitmap 中被置为 1 的位数。UInt64 示例 使用示例

Query

SELECT bitmapCardinality(bitmapBuild([1, 3, 3, 5, 7, 7])) AS res

Response

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

bitmapContains

引入版本：v20.1.0 检查 bitmap 是否包含指定元素。该值会按 bitmap 元素类型的无符号整数进行比较。对于有符号 bitmap，负元素会匹配其对应的无符号值 (例如，Int8 值 -1 匹配 255) 。语法

bitmapContains(bitmap, value)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。- value — 待检查的元素。(U)Int8/16/32/64

返回值 如果 bitmap 包含指定的值，则返回 1，否则返回 0。UInt8 示例 使用示例

Query

SELECT bitmapContains(bitmapBuild([1, 2, 3]), 2) AS res;

Response

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

有符号 bitmap

Query

SELECT bitmapContains(bitmapBuild([-1]::Array(Int8)), 255) AS res;

Response

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

bitmapHasAll

引入版本：v20.1.0 检查第一个 bitmap 是否包含第二个 bitmap 中所有置位的位。语法

bitmapHasAll(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 如果第二个 bitmap 中的所有置位都存在于第一个 bitmap 中，则返回 1，否则返回 0。UInt8 示例 用法示例

Query

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

Response

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

bitmapHasAny

引入版本：v20.1.0 检查第一个 bitmap 是否包含第二个 bitmap 中任意置位。语法

bitmapHasAny(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 如果第二个 bitmap 中的任意位出现在第一个 bitmap 中，则返回 1；否则返回 0。UInt8 示例 使用示例

Query

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

Response

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

bitmapMax

引入版本：v20.1.0 返回 bitmap 中最大的元素，并将其解释为 bitmap 元素类型的无符号整数。对于有符号 bitmap，负值会被视为对应的无符号值 (例如，Int8 值 -1 为 255) 。如果 bitmap 为空，则返回 0。语法

bitmapMax(bitmap)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回 bitmap 中最大的元素，并以 bitmap 元素类型的无符号值表示；如果 bitmap 为空，则返回 0 UInt64 示例 使用示例

Query

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

Response

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

有符号 bitmap

Query

SELECT bitmapMax(bitmapBuild([-128, -1]::Array(Int8))) AS res;

Response

┌─res─┐
│ 255 │
└─────┘

bitmapMin

引入版本：v20.1.0 返回 bitmap 中最小的元素，并将其视为 bitmap 元素类型的无符号整数。对于有符号 bitmap，负值会被视为对应的无符号值 (例如，Int8 值 -128 视为 128) 。如果 bitmap 为空，则返回 UINT32_MAX (如果 bitmap 元素类型宽于 32 位，则返回 UINT64_MAX) 。语法

bitmapMin(bitmap)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回 bitmap 中最小的元素，以 bitmap 元素类型的无符号值表示；如果 bitmap 为空，则返回 UINT32_MAX/UINT64_MAX UInt64 示例 用法示例

Query

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

Response

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

有符号 bitmap

Query

SELECT bitmapMin(bitmapBuild([-128, -1]::Array(Int8))) AS res;

Response

┌─res─┐
│ 128 │
└─────┘

bitmapOr

引入版本：v20.1.0 计算两个 bitmap 的逻辑或 (OR) 。语法

bitmapOr(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回一个 bitmap，包含任一输入 bitmap 中置位的位。AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

bitmapOrCardinality

引入版本：v20.1.0 返回两个 bitmap 逻辑或 (OR) 结果的基数。语法

bitmapOrCardinality(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回两个 bitmap 并集中的置位数。UInt64 示例 用法示例

Query

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

Response

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

bitmapSubsetInRange

引入版本：v20.1.0 返回 bitmap 的一个子集，其中包含值范围 [start, end) 内的元素。元素值按 bitmap 元素类型的无符号整数进行比较。语法

bitmapSubsetInRange(bitmap, start, end)

参数

bitmap — 要从中提取子集的 bitmap。AggregateFunction(groupBitmap, T)。- start — 范围的起始位置 (含) 。UInt* - end — 值范围的结束位置 (不含) 。UInt*

返回值 返回一个仅包含指定值范围内元素的 bitmap AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

bitmapSubsetLimit

引入版本：v20.1.0 返回一个最多包含 cardinality_limit 个元素的子集，其中元素值大于或等于 range_start，并按无符号顺序选取其中最小的值。语法

bitmapSubsetLimit(bitmap, range_start, cardinality_limit)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。- range_start — 范围的起始值 (含) 。UInt32 - cardinality_limit — 子集的最大基数。UInt32

返回值 返回一个 bitmap，其中最多包含 cardinality_limit 个无符号值不小于 range_start 的元素。AggregateFunction(groupBitmap, T) 示例 使用示例

Query

SELECT arraySort(bitmapToArray(bitmapSubsetLimit(bitmapBuild([1, 5, 3, 2, 8]), 3, 2))) AS res;

Response

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

bitmapToArray

自 v20.1.0 引入将 bitmap 转换为其元素组成的数组。数组元素类型与 bitmap 元素类型 T 一致 (有符号或无符号整数) 。它是函数 bitmapBuild 的逆操作。语法

bitmapToArray(bitmap)

参数

bitmap — 要转换的 bitmap。AggregateFunction(groupBitmap, T)。

返回值 返回 bitmap 中包含的元素数组 Array(T) 示例 使用示例

Query

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

Response

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

有符号 bitmap

Query

SELECT arraySort(bitmapToArray(bitmapBuild([-128, -1]::Array(Int8)))) AS res;

Response

┌─res────────┐
│ [-128, -1] │
└────────────┘

bitmapTransform

引入版本：v20.1.0 根据从 from_array 到 to_array 的映射替换 bitmap 中的元素。值会被解释为 bitmap 元素类型的无符号整数 (与 bitmapContains 位于同一值域) 。对于有符号 bitmap，负元素会与其对应的无符号值匹配 (例如，Int8 值 -1 与 255 匹配) 。 to_array 中不适合 bitmap 元素类型的值会引发 BAD_ARGUMENTS。from_array 中不适合该类型的值不会被找到，因此不会应用相应的替换。语法

bitmapTransform(bitmap, from_array, to_array)

参数

bitmap — bitmap 对象。AggregateFunction(groupBitmap, T)。- from_array — 要替换的原始置位组成的 Array。Array(T)。- to_array — 用于替换的新置位组成的 Array。Array(T)。

返回值 返回一个其元素已根据给定映射进行转换的 bitmap AggregateFunction(groupBitmap, T) 示例 用法示例

Query

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

Response

┌─res───────────────┐
│ [1, 3, 5, 20, 40] │
└───────────────────┘

有符号 bitmap

Query

SELECT arraySort(bitmapToArray(bitmapTransform(bitmapBuild([-1, 0]::Array(Int8)), [255], [10]))) AS res;

Response

┌─res─────┐
│ [0, 10] │
└─────────┘

bitmapXor

引入版本：v20.1.0 计算两个 bitmap 的对称差 (XOR) 。语法

bitmapXor(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。 - bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回一个 bitmap，包含存在于任一输入 bitmap 中但不同时存在于两者中的置位。AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

bitmapXorCardinality

引入版本：v20.1.0 返回两个 bitmap 的 XOR (对称差) 的基数。语法

bitmapXorCardinality(bitmap1, bitmap2)

参数

bitmap1 — 第一个 bitmap 对象。AggregateFunction(groupBitmap, T)。- bitmap2 — 第二个 bitmap 对象。AggregateFunction(groupBitmap, T)。

返回值 返回两个 bitmap 的对称差中置位数 UInt64 示例 使用示例

Query

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

Response

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

subBitmap

引入版本：v21.9.0 按无符号值升序跳过 offset 个元素后，返回 bitmap 的一个子集。返回的 bitmap 的最大基数为 cardinality_limit。语法

subBitmap(bitmap, offset, cardinality_limit)

参数

bitmap — Bitmap 对象。AggregateFunction(groupBitmap, T). - offset — 从开头要跳过的置位数量 (从零开始计数) 。UInt32 - cardinality_limit — 子集中最多包含的置位数量。UInt32

返回值 返回一个 bitmap，按无符号值升序跳过 offset 个元素后，最多包含 cardinality_limit 个元素。AggregateFunction(groupBitmap, T) 示例 使用示例

Query

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

Response

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

SQL 参考

数据类型

引擎

函数

格式

接口

设置

系统表

数据湖

bitmapAnd

bitmapAndCardinality

bitmapAndnot

bitmapAndnotCardinality

bitmapBuild

bitmapCardinality

bitmapContains

bitmapHasAll

bitmapHasAny

bitmapMax

bitmapMin

bitmapOr

bitmapOrCardinality

bitmapSubsetInRange

bitmapSubsetLimit

bitmapToArray

bitmapTransform

bitmapXor

bitmapXorCardinality

subBitmap

​bitmapAnd

​bitmapAndCardinality

​bitmapAndnot

​bitmapAndnotCardinality

​bitmapBuild

​bitmapCardinality

​bitmapContains

​bitmapHasAll

​bitmapHasAny

​bitmapMax

​bitmapMin

​bitmapOr

​bitmapOrCardinality

​bitmapSubsetInRange

​bitmapSubsetLimit

​bitmapToArray

​bitmapTransform

​bitmapXor

​bitmapXorCardinality

​subBitmap

bitmapAnd

bitmapAndCardinality

bitmapAndnot

bitmapAndnotCardinality

bitmapBuild

bitmapCardinality

bitmapContains

bitmapHasAll

bitmapHasAny

bitmapMax

bitmapMin

bitmapOr

bitmapOrCardinality

bitmapSubsetInRange

bitmapSubsetLimit

bitmapToArray

bitmapTransform

bitmapXor

bitmapXorCardinality

subBitmap