Tuple関数

以下のドキュメントは、system.functions システムテーブルから自動生成されています。

dotProduct

導入バージョン: v21.11.0 2 つのベクトル (同じ長さのタプルまたは配列) の内積 (スカラー積) を計算します。対応する要素同士の積の総和を返します。構文

dotProduct(vector1, vector2)

別名: scalarProduct 引数

vector1 — 1つ目のベクトル。Array(T) または Tuple(T)
vector2 — 2つ目のベクトル。1つ目のベクトルと同じサイズである必要があります。Array(T) または Tuple(T)

戻り値 2つのベクトルの内積を返します。2つの BFloat16 配列は Float32 として累積され、戻り値も Float32 になります。(U)Int* または Float* または Decimal 例 基本的な使い方

Query

SELECT dotProduct((1, 2), (3, 4))

Response

flattenTuple

導入バージョン: v22.6.0 名前付きのネストされたタプルを平坦化します。返されるタプルの各要素は、入力タプルのパスです。構文

flattenTuple(input)

引数

input — フラット化する名前付きのネストされたタプル。Tuple(n1 T1[, n2 T2, ... ])

戻り値 元の入力からのパスを要素とする出力タプルを返します。Tuple(T) 例 使用例

Query

CREATE TABLE tab(t Tuple(a UInt32, b Tuple(c String, d UInt32))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO tab VALUES ((3, ('c', 4)));

SELECT flattenTuple(t) FROM tab;

Response

┌─flattenTuple(t)─┐
│ (3,'c',4)       │
└─────────────────┘

tuple

導入バージョン: v1.1.0 入力引数をまとめて、タプルを返します。型がそれぞれ T1, T2, … のカラム C1, C2, … に対し、それらの名前が一意で、かつ引用符なしの識別子として扱える場合は、それらのカラムを含む名前付き Tuple(C1 T1, C2 T2, …) 型のタプルを返します。そうでない場合は、Tuple(T1, T2, …) が返されます。この関数の実行コストはありません。タプルは通常、IN 演算子の引数の中間値として、またはラムダ関数の仮引数のリストを作成するために使用されます。タプルはテーブルには書き込めません。この関数は演算子 (x, y, ...) を実装します。構文

tuple([t1[, t2[ ...]])

引数

なし。

戻り値 例 一般的な例

Query

SELECT tuple(1, 2)

Response

(1,2)

tupleConcat

導入バージョン: v23.8.0 引数として渡された複数のタプルを結合します。構文

tupleConcat(tuple1[, tuple2, [...]])

引数

tupleN — Tuple 型の引数を任意個指定できます。Tuple(T)

戻り値 入力タプルのすべての要素を含むタプルを返します。Tuple(T) 例 使用例

Query

SELECT tupleConcat((1, 2), ('a',), (true, false))

Response

(1,2,'a',true,false)

tupleDivide

導入バージョン: v21.11.0 同じサイズの2つ以上のタプルに対して、左から右の順に要素ごとの除算を行います。

ゼロで除算した場合は inf が返されます。

構文

tupleDivide(t1, t2[, tN, ...])

引数

t1 — 最初の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 追加の入力タプルを1つ以上指定します。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 要素ごとの商を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2つのタプル

Query

SELECT tupleDivide((1, 2), (2, 3))

Response

(0.5,0.6666666666666666)

3つのタプル

Query

SELECT tupleDivide((100.0, 60.0), (5.0, 3.0), (2.0, 4.0))

Response

(10,5)

tupleDivideByNumber

導入バージョン: v21.11.0 すべての要素を数値で割ったタプルを返します。

ゼロで除算すると inf を返します。

構文

tupleDivideByNumber(tuple, number)

引数

tuple — 除算対象のタプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
number — 除数。(U)Int* または Float* または Decimal

戻り値 各要素を除算したタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleDivideByNumber((1, 2), 0.5)

Response

(2,4)

tupleElement

導入バージョン: v1.1.0 インデックスまたは名前を指定して、タプルから要素を取り出します。インデックスでアクセスする場合は、1 始まりの数値インデックスを指定する必要があります。名前でアクセスする場合は、要素名を文字列として指定できます (名前付きタプルでのみ機能します) 。負のインデックスもサポートされています。この場合、末尾から数えた対応する要素が選択されます。たとえば、tuple.-1 はタプルの最後の要素です。省略可能な第 3 引数では、アクセスした要素が存在しない場合に、例外をスローする代わりに返すデフォルト値を指定します。すべての引数は定数でなければなりません。この関数のランタイムコストはゼロで、演算子 x.index と x.name を実装しています。構文

tupleElement(tuple, index|name[, default_value])

引数

tuple — タプル、またはタプルの配列。Tuple(T) または Array(Tuple(T))
index — 1 から始まるカラムのインデックス。const UInt8/16/32/64
name — 要素名。const String
default_value — インデックスが範囲外であるか、要素が存在しない場合に返されるデフォルト値。Any

戻り値 指定したインデックスまたは名前の要素を返します。Any 例 インデックスアクセス

Query

SELECT tupleElement((1, 'hello'), 2)

Response

hello

負のインデックス

Query

SELECT tupleElement((1, 'hello'), -1)

Response

hello

テーブル付きの名前付きタプル

Query

CREATE TABLE example (values Tuple(name String, age UInt32)) ENGINE = Memory;
INSERT INTO example VALUES (('Alice', 30));
SELECT tupleElement(values, 'name') FROM example;

Response

Alice

デフォルト値付き

Query

SELECT tupleElement((1, 2), 5, 'not_found')

Response

not_found

演算子の構文

Query

SELECT (1, 'hello').2

Response

hello

tupleHammingDistance

導入バージョン: v21.1.0 同じサイズの 2 つのタプル間のハミング距離を返します。

結果の型は、入力タプルの要素数に基づいて、算術関数と同じ方法で決定されます。

SELECT
    toTypeName(tupleHammingDistance(tuple(0), tuple(0))) AS t1,
    toTypeName(tupleHammingDistance((0, 0), (0, 0))) AS t2,
    toTypeName(tupleHammingDistance((0, 0, 0), (0, 0, 0))) AS t3,
    toTypeName(tupleHammingDistance((0, 0, 0, 0), (0, 0, 0, 0))) AS t4,
    toTypeName(tupleHammingDistance((0, 0, 0, 0, 0), (0, 0, 0, 0, 0))) AS t5

┌─t1────┬─t2─────┬─t3─────┬─t4─────┬─t5─────┐
│ UInt8 │ UInt16 │ UInt32 │ UInt64 │ UInt64 │
└───────┴────────┴────────┴────────┴────────┘

構文

tupleHammingDistance(t1, t2)

引数

t1 — 1 番目のタプル。 Tuple(*)
t2 — 2 番目のタプル。 Tuple(*)

戻り値 ハミング距離を返します。 UInt8/16/32/64 例 使用例

Query

SELECT tupleHammingDistance((1, 2, 3), (3, 2, 1))

Response

MinHashによる類似重複文字列の検出

Query

SELECT tupleHammingDistance(wordShingleMinHash(string), wordShingleMinHashCaseInsensitive(string)) FROM (SELECT 'ClickHouse is a column-oriented database management system for online analytical processing of queries.' AS string)

Response

tupleIntDiv

導入バージョン: v23.8.0 同じサイズの2つ以上のタプルに対して、左から右の順に要素ごとの整数除算を行います。結果として、商からなるタプルを返します。いずれかのタプルに整数以外の要素が含まれる場合は、整数でない各被除数または除数を最も近い整数に丸めて結果を計算します。 0 で除算すると、例外がスローされます。構文

tupleIntDiv(t1, t2[, tN, ...])

引数

t1 — 最初の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 追加の入力タプルを1つ以上。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 整数の商を要素とするタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2つのタプル

Query

SELECT tupleIntDiv((15, 10, 5), (5, 5, 5))

Response

(3,2,1)

Decimal型では

Query

SELECT tupleIntDiv((15, 10, 5), (5.5, 5.5, 5.5))

Response

(2,1,0)

3つのタプル

Query

SELECT tupleIntDiv((120, 60), (4, 3), (2, 4))

Response

(15,5)

tupleIntDivByNumber

導入バージョン: v23.8.0 分子のタプルを指定された分母で整数除算し、商のタプルを返します。入力引数のいずれかに整数以外の要素が含まれている場合は、整数でない各分子または除数を最も近い整数に丸めて結果を計算します。 0 で除算した場合はエラーがスローされます。構文

tupleIntDivByNumber(tuple_num, div)

引数

tuple_num — 分子の値からなる Tuple。Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal)
div — 除数の値。(U)Int* or Float* or Decimal

戻り値 商からなる Tuple を返します。Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleIntDivByNumber((15, 10, 5), 5)

Response

(3,2,1)

小数を使う場合

Query

SELECT tupleIntDivByNumber((15.2, 10.7, 5.5), 5.8)

Response

(2,1,0)

tupleIntDivOrZero

導入バージョン: v23.8.0 tupleIntDiv と同様に、同じサイズの 2 つ以上のタプルに対して、左から右に要素ごとの整数除算を行います。 0 で除算した場合は、例外をスローする代わりにその要素について 0 を返します。いずれかのタプルに整数以外の要素が含まれている場合は、各非整数の分子または除数を最も近い整数に丸めて結果を計算します。構文

tupleIntDivOrZero(t1, t2[, tN, ...])

引数

t1 — 最初の入力 Tuple。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 1 つ以上の追加の入力 Tuple。すべての Tuple は同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 整数の商からなる Tuple を返します。除数が 0 である要素については 0 を返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 除数が 0 の場合

Query

SELECT tupleIntDivOrZero((5, 10, 15), (0, 0, 0))

Response

(0,0,0)

3つのタプル

Query

SELECT tupleIntDivOrZero((120, 60), (4, 3), (2, 4))

Response

(15,5)

tupleIntDivOrZeroByNumber

導入バージョン: v23.8.0 tupleIntDivByNumber と同様に、分子のタプルを指定した分母で整数除算し、商のタプルを返します。除数が 0 の場合でもエラーは発生させず、代わりに商として 0 を返します。タプルまたは分母に整数以外の要素が含まれている場合は、整数でない各分子または除数を最も近い整数に丸めて結果を計算します。構文

tupleIntDivOrZeroByNumber(tuple_num, div)

引数

tuple_num — 分子の値からなる Tuple。Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal)
div — 除数の値。(U)Int* or Float* or Decimal

戻り値 除数が 0 である商を 0 とした、商の Tuple を返します。Tuple((U)Int*) or Tuple(Float*) or Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 5)

Response

(3,2,1)

除数が 0 の場合

Query

SELECT tupleIntDivOrZeroByNumber((15, 10, 5), 0)

Response

(0,0,0)

tupleMinus

導入バージョン: v21.11.0 同じサイズの2つ以上のタプルについて、左から右の順に、対応する要素同士の差を計算します。構文

tupleMinus(t1, t2[, tN, ...])

別名: vectorDifference 引数

t1 — 1番目の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 2番目以降の入力タプルを1つ以上指定します。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 各要素ごとの差分を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2つのタプル

Query

SELECT tupleMinus((1, 2), (2, 3))

Response

(-1,-1)

3つのタプル

Query

SELECT tupleMinus((10, 10), (3, 4), (2, 1))

Response

(5,5)

tupleModulo

導入バージョン: v23.8.0 同じサイズの2つ以上のタプル同士を左から右の順に割り算し、各要素ごとの剰余をまとめたタプルを返します。構文

tupleModulo(t1, t2[, tN, ...])

引数

t1 — 最初の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 追加の入力タプルを 1 つ以上。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 要素ごとの剰余からなるタプルを返します。0 による除算の場合は例外がスローされます。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2 つのタプル

Query

SELECT tupleModulo((15, 10, 5), (5, 3, 2))

Response

(0,1,1)

3つのタプル

Query

SELECT tupleModulo((10, 20), (7, 9), (3, 5))

Response

(0,2)

tupleModuloByNumber

導入バージョン: v23.8.0 タプルの各要素を指定された除数で割ったときの剰余 (剰余) からなるタプルを返します。構文

tupleModuloByNumber(tuple_num, div)

引数

tuple_num — 分子要素のタプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
div — 除数の値。(U)Int* または Float* または Decimal

戻り値 除算の剰余からなるタプルを返します。ゼロ除算の場合はエラーがスローされます。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleModuloByNumber((15, 10, 5), 2)

Response

(1,0,1)

tupleMultiply

導入バージョン: v21.11.0 同じサイズの2つ以上のタプルの要素ごとの積を計算します。構文

tupleMultiply(t1, t2[, tN, ...])

引数

t1 — 1つ目の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 2つ目以降の入力タプルを1つ以上指定します。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 要素ごとの積を格納したタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2つのタプル

Query

SELECT tupleMultiply((1, 2), (2, 3))

Response

(2,6)

3つのタプル

Query

SELECT tupleMultiply((1, 2), (2, 3), (1, 2))

Response

(2,12)

tupleMultiplyByNumber

導入バージョン: v21.11.0 すべての要素に数値を乗算したタプルを返します。構文

tupleMultiplyByNumber(tuple, number)

引数

tuple — 乗算対象のタプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
number — 乗数。(U)Int* または Float* または Decimal

戻り値 要素が乗算されたタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleMultiplyByNumber((1, 2), -2.1)

Response

(-2.1,-4.2)

tupleNames

導入バージョン: v24.8.0 タプルをカラム名の配列に変換します。Tuple(a T, b T, ...) 形式のタプルに対して、タプル内の名前付きカラムを表す文字列の配列を返します。タプル要素に明示的な名前がない場合は、代わりにそのインデックスがカラム名として使用されます。構文

tupleNames(tuple)

引数

なし。

戻り値 例 一般的な例

Query

SELECT tupleNames(tuple(1 as a, 2 as b))

Response

['1','2']

tupleNegate

導入バージョン: v21.11.0 タプルの各要素の符号を反転した値を計算します。構文

tupleNegate(t)

引数

t — 符号反転するタプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 符号反転した結果のタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 基本的な使い方

Query

SELECT tupleNegate((1, 2))

Response

(-1,-2)

tuplePlus

導入バージョン: v21.11.0 同じサイズの2つ以上のタプルの要素ごとの合計を計算します。構文

tuplePlus(t1, t2[, tN, ...])

別名: vectorSum 引数

t1 — 1番目の入力タプル。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
t2, ..., tN — 追加の入力タプルを1つ以上。すべてのタプルは同じサイズである必要があります。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

戻り値 要素ごとの和を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 2つのタプル

Query

SELECT tuplePlus((1, 2), (2, 3))

Response

(3,5)

3つのタプル

Query

SELECT tuplePlus((1, 2), (2, 3), (3, 4))

Response

(6,9)

tuplePositiveModuloByNumber

導入バージョン: v26.4.0 タプルの各要素を指定した除数で割ったときの正の剰余からなるタプルを返します。 tupleModuloByNumber とは異なり、結果は常に非負になります。構文

tuplePositiveModuloByNumber(tuple_num, div)

引数

tuple_num — 分子の値からなる Tuple。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)
div — 除数の値。(U)Int* または Float* または Decimal

戻り値 非負の剰余からなる Tuple を返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal) 例 基本的な使い方

Query

SELECT tuplePositiveModuloByNumber((15, 10, 5), 2)

Response

(1,0,1)

tupleToNameValuePairs

導入バージョン: v21.9.0 タプルを (name, value) のペアからなる配列に変換します。たとえば、タプル Tuple(n1 T1, n2 T2, ...) は Array(Tuple('n1', T1), Tuple('n2', T2), ...) に変換されます。タプル内のすべての値は同じ型である必要があります。構文

tupleToNameValuePairs(tuple)

引数

tuple — 任意の型の値を含む名前付きタプル。Tuple(n1 T1[, n2 T2, ...])

戻り値 (name, value) のペアからなる配列を返します。Array(Tuple(String, T)) 例 名前付きタプル

Query

SELECT tupleToNameValuePairs(tuple(1593 AS user_ID, 2502 AS session_ID))

Response

[('1',1593),('2',2502)]

無名タプル

Query

SELECT tupleToNameValuePairs(tuple(3, 2, 1))

Response

[('1',3),('2',2),('3',1)]

untuple

呼び出し箇所で、tuple の要素を構文的に置き換えます。結果のカラム名は実装依存で、変更される可能性があります。untuple の後で特定のカラム名を前提にしないでください。構文

untuple(x)

EXCEPT 式を使用すると、クエリ結果からカラムを除外できます。引数

x — tuple 関数、カラム、または要素のタプル。Tuple。

戻り値

なし。

例入力テーブル:

┌─key─┬─v1─┬─v2─┬─v3─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 20 │ 40 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 65 │ 70 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 30 │ 20 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 12 │  7 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 50 │ 70 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴────┴────┴───────────┘

Tuple型のカラムをuntuple関数の引数として使用する例:

Query

SELECT untuple(v6) FROM kv;

Response

┌─_ut_1─┬─_ut_2─┐
│    33 │ ab    │
│    44 │ cd    │
│    55 │ ef    │
│    66 │ gh    │
│    77 │ kl    │
└───────┴───────┘

EXCEPT 式の使用例:

Query

SELECT untuple((* EXCEPT (v2, v3),)) FROM kv;

Response

┌─key─┬─v1─┬─v4─┬─v5─┬─v6────────┐
│   1 │ 10 │ 30 │ 15 │ (33,'ab') │
│   2 │ 25 │ 40 │  6 │ (44,'cd') │
│   3 │ 57 │ 10 │  5 │ (55,'ef') │
│   4 │ 55 │ 80 │ 90 │ (66,'gh') │
│   5 │ 30 │ 25 │ 55 │ (77,'kl') │
└─────┴────┴────┴────┴───────────┘

距離関数

サポートされているすべての関数については、距離関数のドキュメントを参照してください。

SQLリファレンス

データ型

エンジン

関数

フォーマット

設定

システムテーブル

データレイク

dotProduct

flattenTuple

tuple

tupleConcat

tupleDivide

tupleDivideByNumber

tupleElement

tupleHammingDistance

tupleIntDiv

tupleIntDivByNumber

tupleIntDivOrZero

tupleIntDivOrZeroByNumber

tupleMinus

tupleModulo

tupleModuloByNumber

tupleMultiply

tupleMultiplyByNumber

tupleNames

tupleNegate

tuplePlus

tuplePositiveModuloByNumber

tupleToNameValuePairs

untuple

距離関数

​dotProduct

​flattenTuple

​tuple

​tupleConcat

​tupleDivide

​tupleDivideByNumber

​tupleElement

​tupleHammingDistance

​tupleIntDiv

​tupleIntDivByNumber

​tupleIntDivOrZero

​tupleIntDivOrZeroByNumber

​tupleMinus

​tupleModulo

​tupleModuloByNumber

​tupleMultiply

​tupleMultiplyByNumber

​tupleNames

​tupleNegate

​tuplePlus

​tuplePositiveModuloByNumber

​tupleToNameValuePairs

​untuple

​距離関数

dotProduct

flattenTuple

tuple

tupleConcat

tupleDivide

tupleDivideByNumber

tupleElement

tupleHammingDistance

tupleIntDiv

tupleIntDivByNumber

tupleIntDivOrZero

tupleIntDivOrZeroByNumber

tupleMinus

tupleModulo

tupleModuloByNumber

tupleMultiply

tupleMultiplyByNumber

tupleNames

tupleNegate

tuplePlus

tuplePositiveModuloByNumber

tupleToNameValuePairs

untuple

距離関数