NumericIndexedVector
NumericIndexedVector は、ベクトルをカプセル化し、ベクトルの集約演算および要素ごとの演算を実装する抽象データ構造です。ストレージ方式として Bit-Sliced Index を利用します。理論的背景およびユースケースについては、論文 Large-Scale Metric Computation in Online Controlled Experiment Platform を参照してください。
BSI
BSI(Bit-Sliced Index)ストレージ方式では、データはまず Bit-Sliced Index として保存され、その後 Roaring Bitmap を用いて圧縮されます。集約演算や要素単位(pointwise)の演算は圧縮データ上で直接実行されるため、ストレージ効率とクエリ効率を大幅に向上できます。
ベクタにはインデックスとそれに対応する値が含まれます。BSI ストレージモードにおけるこのデータ構造の特徴と制約は次のとおりです。
- インデックスタイプは
UInt8、UInt16、UInt32のいずれかです。注意: Roaring Bitmap の 64 ビット実装の性能を考慮し、BSI フォーマットはUInt64/Int64をサポートしません。 - 値の型は
Int8、Int16、Int32、Int64、UInt8、UInt16、UInt32、UInt64、Float32、Float64のいずれかです。注意: 値の型は自動的には拡張されません。たとえば、値の型としてUInt8を使用した場合、UInt8の容量を超える合計値は、より高い型に昇格されるのではなくオーバーフローします。同様に、整数に対する演算は整数結果を返します(たとえば、除算は自動的に浮動小数点結果に変換されません)。したがって、値の型は事前に計画・設計しておくことが重要です。実運用シナリオでは、浮動小数点型(Float32/Float64)が一般的に使用されます。 - 同じインデックスタイプおよび値の型を持つ 2 つのベクタ同士でのみ演算を行えます。
- 下層のストレージは Bit-Sliced Index を使用し、インデックスをビットマップとして保持します。ビットマップの具体的な実装として Roaring Bitmap が使用されます。ベストプラクティスとしては、圧縮率とクエリ性能を最大化するために、可能な限りインデックスを少数の Roaring Bitmap コンテナに集中させることが推奨されます。
- Bit-Sliced Index のメカニズムでは、値は二進数に変換されます。浮動小数点型に対しては固定小数点表現による変換を行うため、精度が失われる可能性があります。精度は、小数部に使用するビット数をカスタマイズすることで調整可能であり、デフォルトは 24 ビットです。これはほとんどのシナリオに十分です。集約関数 groupNumericIndexedVector によって
-Stateを伴う NumericIndexedVector を構築する際に、整数部ビット数と小数部ビット数をカスタマイズできます。 - インデックスには、非ゼロ値、ゼロ値、存在しないものの 3 パターンがあります。NumericIndexedVector では、非ゼロ値とゼロ値のみが保存されます。さらに、2 つの NumericIndexedVector 間での要素単位演算では、存在しないインデックスの値は 0 とみなされます。除算のシナリオでは、除数がゼロの場合、結果はゼロになります。
numericIndexedVector オブジェクトを作成する
この構造を作成する方法は 2 通りあります。1 つは、集約関数 groupNumericIndexedVector に -State を付けて使用する方法です。
追加の条件を指定するには、サフィックスとして -if を付けることができます。
この集約関数は、その条件を満たした行のみを処理します。
もう 1 つは、numericIndexedVectorBuild を使って map から構築する方法です。
groupNumericIndexedVectorState 関数では、パラメータを通じて整数部および小数部のビット数をカスタマイズできますが、numericIndexedVectorBuild ではできません。
groupNumericIndexedVector
2 つのデータ列から NumericIndexedVector を構築し、すべての値の合計を Float64 型で返します。末尾にサフィックス State を付けた場合は、NumericIndexedVector オブジェクトを返します。
構文
パラメータ
type: String、省略可能。ストレージ形式を指定します。現在サポートされているのは'BSI'のみです。integer_bit_num:UInt32、省略可能。'BSI'ストレージ形式で有効であり、このパラメータは整数部に使用されるビット数を示します。インデックスの型が整数型の場合、デフォルト値はインデックスの格納に使用されるビット数に対応します。例えば、インデックスの型が UInt16 の場合、デフォルトのinteger_bit_numは 16 です。インデックスの型が Float32 および Float64 の場合、integer_bit_numのデフォルト値は 40 であり、そのため表現可能なデータの整数部は[-2^39, 2^39 - 1]の範囲になります。許可される範囲は[0, 64]です。fraction_bit_num:UInt32、省略可能。'BSI'ストレージ形式で有効であり、このパラメータは小数部に使用されるビット数を示します。値の型が整数の場合、デフォルト値は 0 です。値の型が Float32 または Float64 の場合、デフォルト値は 24 です。有効な範囲は[0, 24]です。- さらに、
integer_bit_num + fraction_bit_numの有効な範囲も[0, 64]であるという制約があります。 col1: インデックス列。サポートされる型:UInt8/UInt16/UInt32/Int8/Int16/Int32。col2: 値列。サポートされる型:Int8/Int16/Int32/Int64/UInt8/UInt16/UInt32/UInt64/Float32/Float64。
戻り値
すべての値の合計を表す Float64 値。
例
テストデータ:
クエリと結果:
以下のドキュメントは system.functions システムテーブルから自動生成されています。
numericIndexedVectorAllValueSum
導入バージョン: v25.7.0
numericIndexedVector 内のすべての値の合計を返します。
構文
引数
返される値
合計値を返します。Float64
例
使用例
numericIndexedVectorBuild
導入バージョン: v25.7.0
map から NumericIndexedVector を作成します。map のキーはベクトルのインデックスを表し、map の値はベクトル要素の値を表します。
構文
引数
map— インデックスから値へのマッピング。Map
戻り値
NumericIndexedVector オブジェクトを返します。AggregateFunction
例
使用例
numericIndexedVectorCardinality
導入バージョン: v25.7.0
numericIndexedVector のカーディナリティ(一意な索引の数)を返します。
構文
引数
返り値
一意な索引の個数を返します。UInt64
例
使用例
numericIndexedVectorGetValue
導入バージョン: v25.7.0
numericIndexedVector から、指定された索引に対応する値を取得します。
構文
引数
v—numericIndexedVectori— 取得する値に対応する索引。(U)Int*
戻り値
NumericIndexedVector の値の型と同じ型の数値。(U)Int* または Float*
例
使用例
numericIndexedVectorPointwiseAdd
導入バージョン: v25.7.0
numericIndexedVector 同士、または numericIndexedVector と数値定数との要素ごとの加算を行います。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseDivide
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector または数値定数との要素単位の除算を実行します。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*、Float*、またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseEqual
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector または数値定数との間で要素ごとの比較を実行します。
結果は、値が等しい要素のインデックスを含む numericIndexedVector であり、対応する値はすべて 1 に設定されます。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
返される値
新しい numericIndexedVector オブジェクトを返します。
例
numericIndexedVectorPointwiseGreater
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector または数値定数との間で、要素単位の比較を実行します。
結果は、1つ目のベクターの値が 2 つ目のベクターの値より大きいインデックスを含む numericIndexedVector であり、そのインデックスに対応する値はすべて 1 に設定されます。
構文
引数
v1—numericIndexedVectorv2— 数値定数または numericIndexedVector オブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseGreaterEqual
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector もしくは数値定数との要素単位の比較を行います。
結果は、1つ目のベクターの値が2つ目のベクターの値以上であるインデックスを含む numericIndexedVector となり、該当するすべての値は 1 に設定されます。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseLess
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector もしくは数値定数との要素単位の比較を実行します。
結果は、1番目のベクトルの値が2番目のベクトルの値より小さい要素のインデックスを含む numericIndexedVector であり、対応するインデックス位置の値はすべて 1 に設定されます。
構文
引数
v1—numericIndexedVectorv2— 数値定数または numericIndexedVector オブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
戻り値は、新しい numericIndexedVector オブジェクトです。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseLessEqual
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector もしくは数値定数との要素ごとの比較を実行します。
結果は、最初のベクターの値が 2つ目のベクターの値以下であるインデックスを含む numericIndexedVector となり、該当するすべての値は 1 に設定されます。
構文
引数
v1—numericIndexedVectorv2— 数値定数、または(U)Int*やFloat*、numericIndexedVectorのいずれかの型を持つ numericIndexedVector オブジェクト
戻り値
新しい numericIndexedVector オブジェクト(numericIndexedVector)を返します。
例
使用例
numericIndexedVectorPointwiseMultiply
導入バージョン: v25.7.0
numericIndexedVector と別の numericIndexedVector、または数値定数との要素ごとの乗算を実行します。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。
使用例
numericIndexedVectorPointwiseNotEqual
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector もしくは数値定数との間で要素ごとの比較を行います。
結果は、値が等しくない要素のインデックスのみを含み、対応する値がすべて 1 に設定された numericIndexedVector になります。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
戻り値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorPointwiseSubtract
導入バージョン: v25.7.0
numericIndexedVector と、別の numericIndexedVector または数値定数との要素ごとの減算を実行します。
構文
引数
v1—numericIndexedVectorv2— 数値定数またはnumericIndexedVectorオブジェクト。(U)Int*またはFloat*またはnumericIndexedVector
返される値
新しい numericIndexedVector オブジェクトを返します。numericIndexedVector
例
使用例
numericIndexedVectorShortDebugString
導入バージョン: v25.7.0
numericIndexedVector の内部情報を JSON 形式で返します。 この関数は主にデバッグのために使用されます。
構文
引数
戻り値
デバッグ情報を含む JSON 文字列を返します。String
例
使用例
numericIndexedVectorToMap
導入バージョン: v25.7.0
numericIndexedVector を map に変換します。
構文
引数
戻り値
索引と値のペアからなるマップを返します。Map
例
使用例