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

> Документация по функциям битмапов

# Функции битмапов

Битмапы можно создавать двумя способами. Первый — с помощью агрегатной функции groupBitmap с `-State`, второй — из объекта Array.

{/*AUTOGENERATED_START*/}

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

Добавленный в: v20.1.0

Вычисляет логическую операцию И (AND) для двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает битмап, содержащий биты, установленные в обоих входных битмапах [`AggregateFunction(groupBitmap, T)`](/ru/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

Возвращает мощность результата логического И (AND) двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает число установленных битов в пересечении двух битмапов [`UInt64`](/ru/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

Вычисляет разность множеств A AND-NOT B для двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает битмап, содержащий биты, установленные в первом битмапе, но не во втором [`AggregateFunction(groupBitmap, T)`](/ru/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

Возвращает мощность результата операции AND-NOT над двумя битмапами.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает количество установленных битов в результате `bitmap1 AND-NOT bitmap2` [`UInt64`](/ru/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

Создаёт битмап из массива беззнаковых целых чисел. Это функция, обратная [`bitmapToArray`](/ru/reference/functions/regular-functions/bitmap-functions#bitmapToArray).

**Синтаксис**

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

**Аргументы**

* `array` — Массив беззнаковых целых чисел. [`Array(UInt*)`](/ru/reference/data-types/array)

**Возвращаемое значение**

Возвращает битмап из переданного массива [`AggregateFunction(groupBitmap, T)`](/ru/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)        │
└─────┴──────────────────────────────────────────────┘
```

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

Добавленный в: v20.1.0

Возвращает количество установленных битов (мощность) в битмапе.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает количество установленных битов в битмапе [`UInt64`](/ru/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

Проверяет, содержит ли битмап указанный элемент.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `value` — Проверяемый элемент. [(U)Int8/16/32/64](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает `1`, если битмап содержит указанное значение, иначе — `0` [`UInt8`](/ru/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  │
└─────┘
```

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

Добавленный в: v20.1.0

Проверяет, содержит ли первый битмап все установленные биты из второго битмапа.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает `1`, если все установленные биты второго битмапа содержатся в первом битмапе; в противном случае — `0` [`UInt8`](/ru/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

Проверяет, содержит ли первый битмап какие-либо установленные биты из второго битмапа.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает `1`, если хотя бы один бит второго битмапа есть в первом битмапе, иначе — `0` [`UInt8`](/ru/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

Возвращает позицию самого старшего установленного бита в битмапе или `0`, если битмап пуст.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает позицию самого старшего установленного бита в битмапе, иначе — `0` [`UInt64`](/ru/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 │
└─────┘
```

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

Добавленный в: v20.1.0

Возвращает позицию наименьшего установленного бита в битмапе. Если ни один бит не установлен, возвращает `UINT32_MAX` (`UINT64_MAX`, если битмап содержит более `2^64` бит).

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает позицию наименьшего установленного бита в битмапе или `UINT32_MAX`/`UINT64_MAX` [`UInt64`](/ru/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 │
└─────┘
```

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

Добавленный в: v20.1.0

Вычисляет логическое объединение (OR) двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает битмап, содержащий биты, установленные хотя бы в одном из входных битмапов [`AggregateFunction(groupBitmap, T)`](/ru/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

Возвращает мощность результата логической операции OR для двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает число установленных битов в объединении двух битмапов [`UInt64`](/ru/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

Возвращает подмножество битмапа, содержащее только биты, установленные в указанном диапазоне \[start, end). Используется индексация с 1.

**Синтаксис**

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

**Аргументы**

* `bitmap` — битмап, из которого извлекается подмножество. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `start` — начало диапазона (включительно). [`UInt*`](/ru/reference/data-types/int-uint) - `end` — конец диапазона (исключая). [`UInt*`](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает битмап, содержащий только установленные биты из указанного диапазона [`AggregateFunction(groupBitmap, T)`](/ru/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

Возвращает подмножество битмапа, начиная с позиции `range_start`, содержащее не более `cardinality_limit` установленных бит. Используется индексация с единицы.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `range_start` — начало диапазона (включительно). [`UInt32`](/ru/reference/data-types/int-uint) - `cardinality_limit` — максимальная мощность подмножества. [`UInt32`](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает битмап, содержащий не более `cardinality_limit` установленных битов, начиная с `range_start` [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction)

**Примеры**

**Пример использования**

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

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

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

Добавленный в: v20.1.0

Преобразует битмап в массив беззнаковых целых чисел. Это функция, обратная [`bitmapBuild`](/ru/reference/functions/regular-functions/bitmap-functions#bitmapBuild).

**Синтаксис**

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

**Аргументы**

* `bitmap` — битмап, который нужно преобразовать. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Массив беззнаковых целых чисел, содержащихся в битмапе [`Array(UInt*)`](/ru/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] │
└─────────────────┘
```

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

Добавленный в: v20.1.0

Изменяет до N битов в битмапе, заменяя указанные значения битов в `from_array` соответствующими значениями из `to_array`.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `from_array` — Array исходных установленных битов, которые нужно заменить. [`Array(T)`](/ru/reference/data-types/array). - `to_array` — Array новых установленных битов, на которые выполняется замена. [`Array(T)`](/ru/reference/data-types/array).

**Возвращаемое значение**

Возвращает битмап с элементами, преобразованными по заданному соответствию [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction)

**Примеры**

**Пример использования**

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

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

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

Добавленный в: v20.1.0

Вычисляет симметрическую разность (XOR) двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает битмап, содержащий биты, установленные только в одном из входных битмапов [`AggregateFunction(groupBitmap, T)`](/ru/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

Возвращает мощность результата XOR (симметрической разности) двух битмапов.

**Синтаксис**

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

**Аргументы**

* `bitmap1` — Первый объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `bitmap2` — Второй объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction).

**Возвращаемое значение**

Возвращает количество установленных битов в симметрической разности двух битмапов [`UInt64`](/ru/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`. Максимальная мощность возвращаемого битмапа — `cardinality_limit`.

**Синтаксис**

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

**Аргументы**

* `bitmap` — объект битмапа. [`AggregateFunction(groupBitmap, T)`](/ru/reference/data-types/aggregatefunction). - `offset` — количество установленных битов, которые нужно пропустить с начала (отсчёт с нуля). [`UInt32`](/ru/reference/data-types/int-uint) - `cardinality_limit` — максимальное количество установленных битов, включаемых в подмножество. [`UInt32`](/ru/reference/data-types/int-uint)

**Возвращаемое значение**

Возвращает битмап, содержащий не более `limit` установленных битов после пропуска `offset` установленных битов в порядке возрастания [`AggregateFunction(groupBitmap, T)`](/ru/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] │
└────────┘
```