> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Bitmap 函数文档

# Bitmap Functions

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

<div id="bitmapAnd">
  ## bitmapAnd
</div>

首次引入于：v20.1.0

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

**语法**

```sql theme={null}
bitmapAnd(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回一个 bitmap，其中包含两个输入 bitmap 中都存在的位 [`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapAnd(bitmapBuild([1, 2, 3]), bitmapBuild([3, 4, 5]))) AS res;
```

```response title=Response theme={null}
┌─res─┐
│ [3] │
└─────┘
```

<div id="bitmapAndCardinality">
  ## bitmapAndCardinality
</div>

引入于：v20.1.0

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

**语法**

```sql theme={null}
bitmapAndCardinality(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回两个 bitmap 交集中置为 1 的位数。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapAndCardinality(bitmapBuild([1,2,3]), bitmapBuild([3,4,5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   1 │
└─────┘
```

<div id="bitmapAndnot">
  ## bitmapAndnot
</div>

始于版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapAndnot(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回一个 bitmap，包含第一个 bitmap 中已置位但第二个 bitmap 中未置位的位 [`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapAndnot(bitmapBuild([1, 2, 3]), bitmapBuild([3, 4, 5]))) AS res;
```

```response title=Response theme={null}
┌─res────┐
│ [1, 2] │
└────────┘
```

<div id="bitmapAndnotCardinality">
  ## bitmapAndnotCardinality
</div>

引入版本：v20.1.0

返回两个 bitmap 进行 AND-NOT 运算后结果的基数。

**语法**

```sql theme={null}
bitmapAndnotCardinality(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回 `bitmap1 AND-NOT bitmap2` 结果中置位的位数。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapAndnotCardinality(bitmapBuild([1,2,3]), bitmapBuild([3,4,5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   2 │
└─────┘
```

<div id="bitmapBuild">
  ## bitmapBuild
</div>

引入版本：v20.1.0

根据整数数组构建 bitmap。支持的元素类型为 8、16、32 或 64 位有符号和无符号整数。它是函数 [`bitmapToArray`](/zh/reference/functions/regular-functions/bitmap-functions#bitmapToArray) 的逆操作。

**语法**

```sql theme={null}
bitmapBuild(array)
```

**参数**

* `array` — 整数数组。[`Array((U)Int*)`](/zh/reference/data-types/array)

**返回值**

返回由给定数组构建的 bitmap [`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapBuild([1, 2, 3, 4, 5]) AS res, toTypeName(res);
```

```response title=Response theme={null}
┌─res─┬─toTypeName(bitmapBuild([1, 2, 3, 4, 5]))─────┐
│     │ AggregateFunction(groupBitmap, UInt8)        │
└─────┴──────────────────────────────────────────────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT bitmapBuild([-128, -1]::Array(Int8)) AS res, toTypeName(res);
```

```response title=Response theme={null}
┌─res─┬─toTypeName(bitmapBuild([-128, -1]::Array(Int8)))─┐
│     │ AggregateFunction(groupBitmap, Int8)             │
└─────┴──────────────────────────────────────────────────┘
```

<div id="bitmapCardinality">
  ## bitmapCardinality
</div>

引入版本：v20.1.0

返回 bitmap 中置为 1 的位数 (即基数) 。

**语法**

```sql theme={null}
bitmapCardinality(bitmap)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回 bitmap 中被置为 1 的位数。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapCardinality(bitmapBuild([1, 3, 3, 5, 7, 7])) AS res
```

```response title=Response theme={null}
┌─res─┐
│   4 │
└─────┘
```

<div id="bitmapContains">
  ## bitmapContains
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapContains(bitmap, value)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `value` — 待检查的元素。[(U)Int8/16/32/64](/zh/reference/data-types/int-uint)

**返回值**

如果 bitmap 包含指定的值，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapContains(bitmapBuild([1, 2, 3]), 2) AS res;
```

```response title=Response theme={null}
┌─res─┐
│  1  │
└─────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT bitmapContains(bitmapBuild([-1]::Array(Int8)), 255) AS res;
```

```response title=Response theme={null}
┌─res─┐
│  1  │
└─────┘
```

<div id="bitmapHasAll">
  ## bitmapHasAll
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapHasAll(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

如果第二个 bitmap 中的所有置位都存在于第一个 bitmap 中，则返回 `1`，否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapHasAll(bitmapBuild([1, 2, 3]), bitmapBuild([2, 3])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│  1  │
└─────┘
```

<div id="bitmapHasAny">
  ## bitmapHasAny
</div>

引入版本：v20.1.0

检查第一个 bitmap 是否包含第二个 bitmap 中任意置位。

**语法**

```sql theme={null}
bitmapHasAny(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

如果第二个 bitmap 中的任意位出现在第一个 bitmap 中，则返回 `1`；否则返回 `0`。[`UInt8`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapHasAny(bitmapBuild([1, 2, 3]), bitmapBuild([3, 4, 5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│  1  │
└─────┘
```

<div id="bitmapMax">
  ## bitmapMax
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapMax(bitmap)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回 bitmap 中最大的元素，并以 bitmap 元素类型的无符号值表示；如果 bitmap 为空，则返回 `0` [`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapMax(bitmapBuild([1, 2, 3, 4, 5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   5 │
└─────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT bitmapMax(bitmapBuild([-128, -1]::Array(Int8))) AS res;
```

```response title=Response theme={null}
┌─res─┐
│ 255 │
└─────┘
```

<div id="bitmapMin">
  ## bitmapMin
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapMin(bitmap)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回 bitmap 中最小的元素，以 bitmap 元素类型的无符号值表示；如果 bitmap 为空，则返回 `UINT32_MAX`/`UINT64_MAX` [`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapMin(bitmapBuild([3, 5, 2, 6])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   2 │
└─────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT bitmapMin(bitmapBuild([-128, -1]::Array(Int8))) AS res;
```

```response title=Response theme={null}
┌─res─┐
│ 128 │
└─────┘
```

<div id="bitmapOr">
  ## bitmapOr
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapOr(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回一个 bitmap，包含任一输入 bitmap 中置位的位。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapOr(bitmapBuild([1, 2, 3]), bitmapBuild([3, 4, 5]))) AS res;
```

```response title=Response theme={null}
┌─res─────────────┐
│ [1, 2, 3, 4, 5] │
└─────────────────┘
```

<div id="bitmapOrCardinality">
  ## bitmapOrCardinality
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapOrCardinality(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回两个 bitmap 并集中的置位数。[`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapOrCardinality(bitmapBuild([1,2,3]), bitmapBuild([3,4,5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   5 │
└─────┘
```

<div id="bitmapSubsetInRange">
  ## bitmapSubsetInRange
</div>

引入版本：v20.1.0

返回 bitmap 的一个子集，其中包含值范围 `[start, end)` 内的元素。元素值按 bitmap 元素类型的无符号整数进行比较。

**语法**

```sql theme={null}
bitmapSubsetInRange(bitmap, start, end)
```

**参数**

* `bitmap` — 要从中提取 子集 的 bitmap。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `start` — 范围的起始位置 (含) 。[`UInt*`](/zh/reference/data-types/int-uint) - `end` — 值范围的结束位置 (不含) 。[`UInt*`](/zh/reference/data-types/int-uint)

**返回值**

返回一个仅包含指定值范围内元素的 bitmap [`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapSubsetInRange(bitmapBuild([1, 2, 3, 4, 5]), 2, 5)) AS res;
```

```response title=Response theme={null}
┌─res───────┐
│ [2, 3, 4] │
└───────────┘
```

<div id="bitmapSubsetLimit">
  ## bitmapSubsetLimit
</div>

引入版本：v20.1.0

返回一个最多包含 `cardinality_limit` 个元素的子集，其中元素值大于或等于 `range_start`，并按无符号顺序选取其中最小的值。

**语法**

```sql theme={null}
bitmapSubsetLimit(bitmap, range_start, cardinality_limit)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `range_start` — 范围的起始值 (含) 。[`UInt32`](/zh/reference/data-types/int-uint) - `cardinality_limit` — 子集的最大基数。[`UInt32`](/zh/reference/data-types/int-uint)

**返回值**

返回一个 bitmap，其中最多包含 `cardinality_limit` 个无符号值不小于 `range_start` 的元素。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT arraySort(bitmapToArray(bitmapSubsetLimit(bitmapBuild([1, 5, 3, 2, 8]), 3, 2))) AS res;
```

```response title=Response theme={null}
┌─res────┐
│ [3, 5] │
└────────┘
```

<div id="bitmapToArray">
  ## bitmapToArray
</div>

自 v20.1.0 引入

将 bitmap 转换为其元素组成的数组。数组元素类型与 bitmap 元素类型 `T` 一致 (有符号或无符号整数) 。它是函数 [`bitmapBuild`](/zh/reference/functions/regular-functions/bitmap-functions#bitmapBuild) 的逆操作。

**语法**

```sql theme={null}
bitmapToArray(bitmap)
```

**参数**

* `bitmap` — 要转换的 bitmap。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回 bitmap 中包含的元素数组 [`Array(T)`](/zh/reference/data-types/array)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapBuild([1, 2, 3, 4, 5])) AS res;
```

```response title=Response theme={null}
┌─res─────────────┐
│ [1, 2, 3, 4, 5] │
└─────────────────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT arraySort(bitmapToArray(bitmapBuild([-128, -1]::Array(Int8)))) AS res;
```

```response title=Response theme={null}
┌─res────────┐
│ [-128, -1] │
└────────────┘
```

<div id="bitmapTransform">
  ## bitmapTransform
</div>

引入版本：v20.1.0

根据从 `from_array` 到 `to_array` 的映射替换 bitmap 中的元素。
值会被解释为 bitmap 元素类型的无符号整数 (与 [`bitmapContains`](/zh/reference/functions/regular-functions/bitmap-functions#bitmapContains) 位于同一值域) 。
对于有符号 bitmap，负元素会与其对应的无符号值匹配 (例如，`Int8` 值 `-1` 与 `255` 匹配) 。
`to_array` 中不适合 bitmap 元素类型的值会引发 `BAD_ARGUMENTS`。`from_array` 中
不适合该类型的值不会被找到，因此不会应用相应的替换。

**语法**

```sql theme={null}
bitmapTransform(bitmap, from_array, to_array)
```

**参数**

* `bitmap` — bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `from_array` — 要替换的原始置位组成的 Array。[`Array(T)`](/zh/reference/data-types/array)。- `to_array` — 用于替换的新置位组成的 Array。[`Array(T)`](/zh/reference/data-types/array)。

**返回值**

返回一个其元素已根据给定映射进行转换的 bitmap [`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**用法示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapBuild([1, 2, 3, 4, 5]), [2, 4], [20, 40])) AS res;
```

```response title=Response theme={null}
┌─res───────────────┐
│ [1, 3, 5, 20, 40] │
└───────────────────┘
```

**有符号 bitmap**

```sql title=Query theme={null}
SELECT arraySort(bitmapToArray(bitmapTransform(bitmapBuild([-1, 0]::Array(Int8)), [255], [10]))) AS res;
```

```response title=Response theme={null}
┌─res─────┐
│ [0, 10] │
└─────────┘
```

<div id="bitmapXor">
  ## bitmapXor
</div>

引入版本：v20.1.0

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

**语法**

```sql theme={null}
bitmapXor(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。 - `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回一个 bitmap，包含存在于任一输入 bitmap 中但不同时存在于两者中的置位。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(bitmapXor(bitmapBuild([1, 2, 3]), bitmapBuild([3, 4, 5]))) AS res;
```

```response title=Response theme={null}
┌─res──────────┐
│ [1, 2, 4, 5] │
└──────────────┘
```

<div id="bitmapXorCardinality">
  ## bitmapXorCardinality
</div>

引入版本：v20.1.0

返回两个 bitmap 的 XOR (对称差) 的基数。

**语法**

```sql theme={null}
bitmapXorCardinality(bitmap1, bitmap2)
```

**参数**

* `bitmap1` — 第一个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。- `bitmap2` — 第二个 bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)。

**返回值**

返回两个 bitmap 的对称差中置位数 [`UInt64`](/zh/reference/data-types/int-uint)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapXorCardinality(bitmapBuild([1,2,3]), bitmapBuild([3,4,5])) AS res;
```

```response title=Response theme={null}
┌─res─┐
│   4 │
└─────┘
```

<div id="subBitmap">
  ## subBitmap
</div>

引入版本：v21.9.0

按无符号值升序跳过 `offset` 个元素后，返回 bitmap 的一个子集。返回的 bitmap 的最大基数为 `cardinality_limit`。

**语法**

```sql theme={null}
subBitmap(bitmap, offset, cardinality_limit)
```

**参数**

* `bitmap` — Bitmap 对象。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction). - `offset` — 从开头要跳过的置位数量 (从零开始计数) 。[`UInt32`](/zh/reference/data-types/int-uint) - `cardinality_limit` — 子集中最多包含的置位数量。[`UInt32`](/zh/reference/data-types/int-uint)

**返回值**

返回一个 bitmap，按无符号值升序跳过 `offset` 个元素后，最多包含 `cardinality_limit` 个元素。[`AggregateFunction(groupBitmap, T)`](/zh/reference/data-types/aggregatefunction)

**示例**

**使用示例**

```sql title=Query theme={null}
SELECT bitmapToArray(subBitmap(bitmapBuild([1, 2, 3, 4, 5]), 2, 2)) AS res;
```

```response title=Response theme={null}
┌─res────┐
│ [3, 4] │
└────────┘
```