Bitmap 函数

Bitmaps 可以通过两种方式构造。第一种方式是通过聚合函数 groupBitmap 与 -State 构造，另一种方式是从 Array 对象构造 bitmap。

bitmapAnd

引入于: v20.1

计算两个 bitmap 的逻辑与 (AND)。

语法

bitmapAnd(bitmap1, bitmap2)

参数

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

返回值

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

示例

使用示例

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

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

bitmapAndCardinality

引入于: v20.1

返回两个 bitmap 逻辑与 (AND) 的基数。

语法

bitmapAndCardinality(bitmap1, bitmap2)

参数

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

返回值

返回两个 bitmap 交集中的设置位数 UInt64

示例

使用示例

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

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

bitmapAndnot

引入于: v20.1

计算两个 bitmap 的集合差 A AND-NOT B。

语法

bitmapAndnot(bitmap1, bitmap2)

参数

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

返回值

返回一个 bitmap，其中包含第一个 bitmap 中存在的位，但第二个 bitmap 中不存在 AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapAndnotCardinality

引入于: v20.1

返回两个 bitmap 的 AND-NOT 操作的基数。

语法

bitmapAndnotCardinality(bitmap1, bitmap2)

参数

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

返回值

返回 bitmap1 AND-NOT bitmap2 的结果中设置的位数 UInt64

示例

使用示例

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

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

bitmapBuild

引入于: v20.1

从无符号整数数组构建 bitmap。它是函数 bitmapToArray 的相反操作。

语法

bitmapBuild(array)

参数

• array — 无符号整数数组。 Array(UInt*)

返回值

从提供的数组返回 bitmap AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapCardinality

引入于: v20.1

返回 bitmap 中设置的位数（基数）。

语法

bitmapCardinality(bitmap)

参数

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

返回值

返回 bitmap 中设置的位数 UInt64

示例

使用示例

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

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

bitmapContains

引入于: v20.1

检查 bitmap 是否包含特定元素。

语法

bitmapContains(bitmap, value)

参数

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

返回值

如果 bitmap 包含指定值，则返回 1，否则返回 0 UInt8

示例

使用示例

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

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

bitmapHasAll

引入于: v20.1

检查第一个 bitmap 是否包含第二个 bitmap 的所有设置位。

语法

bitmapHasAll(bitmap1, bitmap2)

参数

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

返回值

如果第二个 bitmap 的所有设置位都存在于第一个 bitmap 中，则返回 1，否则返回 0 UInt8

示例

使用示例

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

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

bitmapHasAny

引入于: v20.1

检查第一个 bitmap 是否包含第二个 bitmap 的任何设置位。

语法

bitmapHasAny(bitmap1, bitmap2)

参数

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

返回值

如果第二个 bitmap 的任何位都存在于第一个 bitmap 中，则返回 1，否则返回 0 UInt8

示例

使用示例

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

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

bitmapMax

引入于: v20.1

返回 bitmap 中最大设置位的索引，如果 bitmap 为空，则返回 0。

语法

bitmapMax(bitmap)

参数

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

返回值

返回 bitmap 中最大设置位的索引，否则返回 0 UInt64

示例

使用示例

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

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

bitmapMin

引入于: v20.1

返回 bitmap 中最小设置位的索引。如果所有位都未设置，或者 UINT32_MAX（如果 bitmap 包含超过 2^64 位，则为 UINT64_MAX）。

语法

bitmapMin(bitmap)

参数

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

返回值

返回 bitmap 中最小设置位的索引，或者 UINT32_MAX/UINT64_MAX UInt64

示例

使用示例

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

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

bitmapOr

引入于: v20.1

计算两个 bitmap 的逻辑或 (OR)。

语法

bitmapOr(bitmap1, bitmap2)

参数

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

返回值

返回一个 bitmap，其中包含任一输入 bitmap 中存在的设置位 AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapOrCardinality

引入于: v20.1

返回两个 bitmap 逻辑或 (OR) 的基数。

语法

bitmapOrCardinality(bitmap1, bitmap2)

参数

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

返回值

返回两个 bitmap 并集的设置位数 UInt64

示例

使用示例

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

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

bitmapSubsetInRange

引入于: v20.1

返回 bitmap 的子集，仅包含指定范围 [start, end) 中的设置位。使用基于 1 的索引。

语法

bitmapSubsetInRange(bitmap, start, end)

参数

• bitmap — 从中提取子集的 bitmap。 AggregateFunction(groupBitmap, T)。 - start — 范围的开始（包括）。 UInt* - end — 范围的结束（不包括）。 UInt*

返回值

返回一个 bitmap，其中仅包含指定范围内的设置位 AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapSubsetLimit

引入于: v20.1

返回 bitmap 的子集，从位置 range_start 开始，最多包含 cardinality_limit 个设置位。使用基于 1 的索引。

语法

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)

示例

使用示例

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

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

bitmapToArray

引入于: v20.1

将 bitmap 转换为无符号整数数组。它是函数 bitmapBuild 的相反操作。

语法

bitmapToArray(bitmap)

参数

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

返回值

返回 bitmap 中包含的无符号整数数组 Array(UInt*)

示例

使用示例

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

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

bitmapTransform

引入于: v20.1

通过在 from_array 中交换特定的位值与 to_array 中的相应位值，更改 bitmap 中最多 N 个位。

语法

bitmapTransform(bitmap, from_array, to_array)

参数

• bitmap — Bitmap 对象。 AggregateFunction(groupBitmap, T)。 - from_array — 要替换的原始设置位的数组。 Array(T)。 - to_array — 要替换为的新设置位的数组。 Array(T)。

返回值

返回根据给定映射转换元素的 bitmap AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapXor

引入于: v20.1

计算两个 bitmap 的对称差 (XOR)。

语法

bitmapXor(bitmap1, bitmap2)

参数

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

返回值

返回一个 bitmap，其中包含任一输入 bitmap 中存在的设置位，但不同时存在于两者中 AggregateFunction(groupBitmap, T)

示例

使用示例

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

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

bitmapXorCardinality

引入于: v20.1

返回两个 bitmap 的 XOR（对称差）的基数。

语法

bitmapXorCardinality(bitmap1, bitmap2)

参数

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

返回值

返回两个 bitmap 对称差中的设置位数 UInt64

示例

使用示例

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

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

subBitmap

引入于: v21.9

返回 bitmap 的子集，从位置 offset 开始。返回 bitmap 的最大基数为 cardinality_limit。

语法

subBitmap(bitmap, offset, cardinality_limit)

参数

• bitmap — Bitmap 对象。 AggregateFunction(groupBitmap, T)。 - offset — 从开头跳过的设置位数（从零开始）。 UInt32 - cardinality_limit — 子集中包含的最大设置位数。 UInt32

返回值

返回一个 bitmap，其中包含最多 limit 个设置位，从跳过 offset 个设置位后开始，按升序排列 AggregateFunction(groupBitmap, T)

示例

使用示例

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

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