Bitmap Functions | ClickHouse Docs

bitmap は 2 つの方法で構築できます。1 つ目は、集約関数 groupBitmap に -State を付けて構築する方法です。もう 1 つは、Array オブジェクトから bitmap を構築する方法です。

bitmapAnd

導入バージョン: v20.1.0

2 つの bitmap の論理積 (AND) を計算します。

構文

bitmapAnd(bitmap1, bitmap2)

引数

bitmap1 — 最初のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - bitmap2 — 2 番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

両方の入力ビットマップに共通して存在するビットを含むビットマップを返します AggregateFunction(groupBitmap, T)

例

使用例

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

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

bitmapAndCardinality

導入バージョン: v20.1.0

2 つの bitmap の論理積 (AND) のカーディナリティを返します。

構文

bitmapAndCardinality(bitmap1, bitmap2)

引数

bitmap1 — 1 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T). - bitmap2 — 2 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T).

戻り値

2 つのビットマップの積集合に含まれる、セットされたビットの数を返します UInt64

例

使用例

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

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

bitmapAndnot

導入バージョン: v20.1.0

2つのビットマップの集合差 A AND-NOT B を計算します。

構文

bitmapAndnot(bitmap1, bitmap2)

引数

bitmap1 — 1 番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - bitmap2 — 2 番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

1 番目のビットマップにはあり、2 番目のビットマップにはないセットビットを含むビットマップを返します。AggregateFunction(groupBitmap, T)

例

使用例

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

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

bitmapAndnotCardinality

導入バージョン: v20.1.0

2 つの bitmap に対する AND-NOT (差) 演算のカーディナリティを返します。

構文

bitmapAndnotCardinality(bitmap1, bitmap2)

引数

bitmap1 — 1つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T). - bitmap2 — 2つ目のビットマップオブジェクト。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.0

整数配列からビットマップを生成します。サポートされる要素型は、8、16、32、64 bit の符号付き整数および符号なし整数です。これは関数 bitmapToArray とは逆の処理です。

構文

bitmapBuild(array)

引数

array — 整数配列。Array((U)Int*)

戻り値

指定された配列から生成されたビットマップを返します AggregateFunction(groupBitmap, T)

例

使用例

-- A bitmap is a binary value, so it is shown with `hex`.
SELECT hex(bitmapBuild([1, 2, 3, 4, 5])) AS res, toTypeName(bitmapBuild([1, 2, 3, 4, 5])) AS type;

┌─res────────────┬─type──────────────────────────────────┐
│ 00050102030405 │ AggregateFunction(groupBitmap, UInt8) │
└────────────────┴───────────────────────────────────────┘

符号付きビットマップ

-- A bitmap is a binary value, so it is shown with `hex`.
SELECT hex(bitmapBuild([-128, -1]::Array(Int8))) AS res, toTypeName(bitmapBuild([-128, -1]::Array(Int8))) AS type;

┌─res──────┬─type─────────────────────────────────┐
│ 000280FF │ AggregateFunction(groupBitmap, Int8) │
└──────────┴──────────────────────────────────────┘

bitmapCardinality

導入バージョン: v20.1.0

bitmap 内でセットされているビット数 (カーディナリティ) を返します。

構文

bitmapCardinality(bitmap)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

ビットマップ内でセットされているビットの数を返します。 UInt64

例

使用例

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

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

bitmapContains

導入バージョン: v20.1.0

ビットマップに特定の要素が含まれているかどうかを判定します。値はビットマップの要素型の符号なし整数として比較されます。符号付きビットマップでは、負の要素は対応する符号なしの値と一致します (例: Int8 の値 -1 は 255 と一致します) 。

構文

bitmapContains(bitmap, value)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - value — 確認対象の要素。(U)Int8/16/32/64

戻り値

ビットマップに指定された値が含まれている場合は 1、それ以外は 0 を返します UInt8

例

使用例

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

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

符号付きビットマップ

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

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

bitmapHasAll

導入バージョン: v20.1.0

1番目のビットマップに、2番目のビットマップで1に設定されているすべてのセットビットが含まれているかどうかを確認します。

構文

bitmapHasAll(bitmap1, bitmap2)

引数

bitmap1 — 1 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - bitmap2 — 2 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

2 つ目のビットマップでセットされているすべてのセットビットが 1 つ目のビットマップに含まれている場合は 1、そうでない場合は 0 を返します UInt8

例

使用例

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

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

bitmapHasAny

導入バージョン: v20.1.0

1つ目のビットマップに、2つ目のビットマップでセットされているセットビットが1つでも含まれているかどうかを確認します。

構文

bitmapHasAny(bitmap1, bitmap2)

引数

bitmap1 — 1 番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T). - bitmap2 — 2 番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T).

戻り値

2 番目のビットマップのいずれかのビットが 1 番目のビットマップに含まれている場合は 1、それ以外の場合は 0 を返します。UInt8

例

使用例

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

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

bitmapMax

導入バージョン: v20.1.0

ビットマップ内の最大要素を、ビットマップの要素型の符号なし整数として解釈して返します。符号付きビットマップの場合、負の値は対応する符号なしの値として扱われます (たとえば、Int8 の値 -1 は 255 です) 。ビットマップが空の場合は 0 を返します。

構文

bitmapMax(bitmap)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

ビットマップ要素型の符号なし値として最大の要素を返します。ビットマップが空の場合は 0 を返します。UInt64

例

使用例

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

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

符号付きビットマップ

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

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

bitmapMin

導入バージョン: v20.1.0

ビットマップ内の最小要素を、ビットマップの要素型に対応する符号なし整数として解釈して返します。符号付きビットマップの場合、負の値は対応する符号なし値として扱われます (例: Int8 型の値 -128 は 128 として扱われます) 。ビットマップが空の場合は UINT32_MAX を返します (ビットマップの要素型が 32 ビットより広い場合は UINT64_MAX) 。

構文

bitmapMin(bitmap)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

ビットマップの要素型における最小要素を符号なし値として返します。ビットマップが空の場合は UINT32_MAX/UINT64_MAX を返します。UInt64

例

使用例

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

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

符号付きビットマップ

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

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

bitmapOr

導入バージョン: v20.1.0

2 つのビットマップの論理和 (OR) を計算します。

構文

bitmapOr(bitmap1, bitmap2)

引数

bitmap1 — 1 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - bitmap2 — 2 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

いずれかの入力ビットマップに含まれる、セットビットを持つビットマップを返します 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.0

2 つのビットマップの論理和 (OR) のカーディナリティを返します。

構文

bitmapOrCardinality(bitmap1, bitmap2)

引数

bitmap1 — 最初のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - bitmap2 — 2番目のビットマップオブジェクト。AggregateFunction(groupBitmap, T)。

戻り値

2 つのビットマップのユニオンにおけるセットビット数を返します。UInt64

例

使用例

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

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

bitmapSubsetInRange

導入バージョン: v20.1.0

値の範囲 [start, end) 内の要素を含むビットマップの部分集合を返します。要素の値はビットマップの要素型の符号なし整数として比較されます。

構文

bitmapSubsetInRange(bitmap, start, end)

引数

bitmap — 部分集合を抽出する対象のビットマップ。AggregateFunction(groupBitmap, T)。 - start — 範囲の開始 (含む) 。UInt* - end — 範囲の終了 (含まない) 。UInt*

戻り値

指定した値の範囲内の要素のみを含むビットマップを返します AggregateFunction(groupBitmap, T)

例

使用例

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

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

bitmapSubsetLimit

導入バージョン: v20.1.0

値が range_start 以上の要素のうち、符号なし順序で最小の値から最大 cardinality_limit 個を選択した部分集合を返します。

構文

bitmapSubsetLimit(bitmap, range_start, cardinality_limit)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T)。 - range_start — 範囲の開始 (この値を含む) 。UInt32 - cardinality_limit — 部分集合の最大カーディナリティ。UInt32

戻り値

符号なしの値が range_start 以上の要素を最大 cardinality_limit 個含むビットマップを返します。AggregateFunction(groupBitmap, T)

例

使用例

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

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

bitmapToArray

導入バージョン: v20.1.0

ビットマップをその要素の配列に変換します。配列要素の型はビットマップの要素型 T (符号付きまたは符号なし整数) と一致します。関数 bitmapBuild の逆の操作です。

構文

bitmapToArray(bitmap)

引数

bitmap — 変換対象のビットマップ。AggregateFunction(groupBitmap, T)。

戻り値

ビットマップに含まれる要素の配列を返します。Array(T)

例

使用例

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

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

符号付きビットマップ

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

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

bitmapTransform

導入バージョン: v20.1.0

from_array から to_array へのマッピングに従って、ビットマップ内の要素を置き換えます。値はビットマップ要素型の符号なし整数として解釈されます (bitmapContains と同じドメイン) 。符号付きビットマップでは、負の要素は対応する符号なしの要素と一致します (たとえば、Int8 値の -1 は 255 と一致します) 。 to_array 内の値がビットマップ要素型に収まらない場合は、BAD_ARGUMENTS が送出されます。from_array 内の値が収まらない場合は単に見つからないため、対応する置換は適用されません。

構文

bitmapTransform(bitmap, from_array, to_array)

引数

bitmap — ビットマップオブジェクト。 AggregateFunction(groupBitmap, T). - from_array — 置き換える元のセットビットの Array。 Array(T). - to_array — 置き換え先となる新しいセットビットの Array。 Array(T).

戻り値

指定されたマッピングに従って要素が変換されたビットマップを返します。AggregateFunction(groupBitmap, T)

例

使用例

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

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

符号付きビットマップ

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

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

bitmapXor

導入バージョン: v20.1.0

2 つのビットマップの対称差 (XOR) を返します。

構文

bitmapXor(bitmap1, bitmap2)

引数

bitmap1 — 1 つ目のビットマップオブジェクト。 AggregateFunction(groupBitmap, T). - bitmap2 — 2 つ目のビットマップオブジェクト。 AggregateFunction(groupBitmap, T).

戻り値

どちらか一方の入力ビットマップにのみ存在するセットビットを含むビットマップを返します AggregateFunction(groupBitmap, T)

例

使用例

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

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

bitmapXorCardinality

導入バージョン: v20.1.0

2 つの bitmap の XOR (対称差) のカーディナリティを返します。

構文

bitmapXorCardinality(bitmap1, bitmap2)

引数

bitmap1 — 1 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T). - bitmap2 — 2 つ目のビットマップオブジェクト。AggregateFunction(groupBitmap, T).

戻り値

2 つのビットマップの対称差における、セットされたビットの数を返します。UInt64

例

使用例

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

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

subBitmap

導入バージョン: v21.9.0

符号なし値の昇順で offset 個の要素をスキップした後のビットマップの部分集合を返します。返されるビットマップの最大カーディナリティは cardinality_limit です。

構文

subBitmap(bitmap, offset, cardinality_limit)

引数

bitmap — ビットマップオブジェクト。AggregateFunction(groupBitmap, T). - offset — 先頭からスキップするセットビット数 (0ベース) 。UInt32 - cardinality_limit — 部分集合に含めるセットビットの最大数。UInt32

戻り値

符号なし値の昇順で offset 個の要素をスキップした後、最大 cardinality_limit 個の要素を含むビットマップを返します AggregateFunction(groupBitmap, T)

例

使用例

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

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