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

> Documentação das funções de bitmap

# Funções de bitmap

Bitmaps podem ser construídos de duas formas. A primeira é por meio da função de agregação groupBitmap com `-State`; a outra é construir um bitmap a partir de um objeto Array.

{/*AUTOGENERATED_START*/}

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

Introduzido em: v20.1.0

Calcula a conjunção lógica (AND) de dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna um bitmap contendo os bits presentes em ambos os bitmaps de entrada [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a cardinalidade da conjunção lógica (AND) de dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna o número de bits definidos na interseção entre os dois bitmaps [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Calcula a diferença de conjuntos A AND-NOT B entre dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto de bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto de bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna um bitmap que contém os bits definidos presentes no primeiro bitmap, mas não no segundo [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a cardinalidade da operação AND-NOT entre dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna o número de bits definidos no resultado de `bitmap1 AND-NOT bitmap2` [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Cria um bitmap a partir de um array de inteiros sem sinal. É o oposto da função [`bitmapToArray`](/pt-BR/reference/functions/regular-functions/bitmap-functions#bitmapToArray).

**Sintaxe**

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

**Argumentos**

* `array` — Array de inteiros sem sinal. [`Array(UInt*)`](/pt-BR/reference/data-types/array)

**Valor retornado**

Retorna um bitmap do array fornecido [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna o número de bits definidos (a cardinalidade) no bitmap.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna o número de bits definidos no bitmap [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Disponível a partir da versão: v20.1.0

Verifica se o bitmap contém um elemento específico.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto de bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `value` — Elemento a ser verificado. [(U)Int8/16/32/64](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna `1` se o bitmap contiver o valor especificado; caso contrário, `0` [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Verifica se o primeiro bitmap contém todos os bits definidos no segundo bitmap.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto de bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto de bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna `1` se todos os bits definidos do segundo bitmap estiverem presentes no primeiro bitmap; caso contrário, `0` [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Verifica se o primeiro bitmap contém algum dos bits definidos no segundo bitmap.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna `1` se algum bit do segundo bitmap estiver presente no primeiro bitmap; caso contrário, `0` [`UInt8`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a posição do bit definido de maior valor em um bitmap, ou `0` se o bitmap estiver vazio.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna a posição do bit de maior valor definido no bitmap; caso contrário, `0` [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a posição do menor bit definido em um bitmap. Se nenhum bit estiver definido, ou `UINT32_MAX` (`UINT64_MAX` se o bitmap contiver mais de `2^64` bits).

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna a posição do menor bit definido no bitmap ou `UINT32_MAX`/`UINT64_MAX` [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Calcula a disjunção lógica (OR) de dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna um bitmap contendo os bits definidos presentes em um ou outro bitmap de entrada [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a cardinalidade da disjunção lógica (OR) de dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna o número de bits definidos na união dos dois bitmaps [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna um subconjunto do bitmap, contendo apenas os bits definidos no intervalo especificado \[start, end). Usa indexação iniciada em 1.

**Sintaxe**

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

**Argumentos**

* `bitmap` — bitmap da qual extrair o subconjunto. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `start` — Início do intervalo (inclusivo). [`UInt*`](/pt-BR/reference/data-types/int-uint) - `end` — Fim do intervalo (exclusivo). [`UInt*`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um bitmap contendo apenas os bits definidos no intervalo especificado [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna um subconjunto de um bitmap a partir da posição `range_start`, com no máximo `cardinality_limit` bits definidos. A indexação começa em 1.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `range_start` — Início do intervalo (inclusivo). [`UInt32`](/pt-BR/reference/data-types/int-uint) - `cardinality_limit` — Cardinalidade máxima do subconjunto. [`UInt32`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um bitmap contendo no máximo `cardinality_limit` bits definidos, a partir de `range_start` [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Converte um bitmap em um array de números inteiros sem sinal. É o oposto da função [`bitmapBuild`](/pt-BR/reference/functions/regular-functions/bitmap-functions#bitmapBuild).

**Sintaxe**

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

**Argumentos**

* `bitmap` — bitmap a ser convertido. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna um array com os inteiros sem sinal contidos no bitmap [`Array(UInt*)`](/pt-BR/reference/data-types/array)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Altera até N bits em um bitmap, substituindo valores de bits específicos em `from_array` pelos correspondentes em `to_array`.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `from_array` — Array dos bits definidos originais que serão substituídos. [`Array(T)`](/pt-BR/reference/data-types/array). - `to_array` — Array dos novos bits definidos usados na substituição. [`Array(T)`](/pt-BR/reference/data-types/array).

**Valor retornado**

Retorna um bitmap com os elementos transformados de acordo com o mapeamento fornecido [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Calcula a diferença simétrica (XOR) entre dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna um bitmap contendo os bits definidos como 1 presentes em um ou outro bitmap de entrada, mas não em ambos [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido em: v20.1.0

Retorna a cardinalidade do XOR (diferença simétrica) de dois bitmaps.

**Sintaxe**

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

**Argumentos**

* `bitmap1` — Primeiro objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `bitmap2` — Segundo objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction).

**Valor retornado**

Retorna o número de bits definidos na diferença simétrica entre os dois bitmaps [`UInt64`](/pt-BR/reference/data-types/int-uint)

**Exemplos**

**Exemplo de uso**

```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>

Introduzido na versão: v21.9.0

Retorna um subconjunto do bitmap, a partir da posição `offset`. A cardinalidade máxima do bitmap retornado é `cardinality_limit`.

**Sintaxe**

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

**Argumentos**

* `bitmap` — Objeto bitmap. [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction). - `offset` — Número de bits definidos a ignorar desde o início (indexação começando em zero). [`UInt32`](/pt-BR/reference/data-types/int-uint) - `cardinality_limit` — Número máximo de bits definidos a incluir no subconjunto. [`UInt32`](/pt-BR/reference/data-types/int-uint)

**Valor retornado**

Retorna um bitmap contendo no máximo `limit` bits definidos, após ignorar `offset` bits definidos em ordem crescente [`AggregateFunction(groupBitmap, T)`](/pt-BR/reference/data-types/aggregatefunction)

**Exemplos**

**Exemplo de uso**

```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] │
└────────┘
```