メインコンテンツへスキップ
メインコンテンツへスキップ

タプル関数

注記

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

flattenTuple​

導入バージョン: v22.6

名前付きかつネストされたタプルをフラット化します。 返されるタプルの要素は、入力タプル内の要素を指すパスになります。

構文

flattenTuple(input)

引数

返される値

元の入力内のパスを要素とする出力タプルを返します。Tuple(T)

例

使用例

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;

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

tuple​

導入バージョン: v

入力引数をグループ化してタプルを返します。

型が T1, T2, ... のカラム C1, C2, ... に対して、名前が一意であり、クォートされていない識別子として扱える場合には、それらのカラムを含む名前付き Tuple(C1 T1, C2 T2, ...) 型のタプルを返し、そうでない場合には Tuple(T1, T2, ...) を返します。関数の実行コストは発生しません。 タプルは通常、IN 演算子の引数用の中間値として、またはラムダ関数の形式パラメータのリストを作成するために使用されます。タプルをテーブルに書き込むことはできません。

この関数は演算子 (x, y, ...) を実装します。

構文

引数

  • なし。

戻り値

例

典型例

SELECT tuple(1, 2)

(1,2)

tupleConcat​

導入バージョン: v23.8

引数として渡されたタプル同士を結合します。

構文

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

引数

  • tupleN — 任意個数の Tuple 型の引数。Tuple(T)

戻り値

入力タプルに含まれるすべての要素を持つタプルを返します。Tuple(T)

例

使用例

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

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

tupleDivide​

導入バージョン: v21.11

同じ長さの 2 つのタプルにおける、対応する要素同士の除算を計算します。

注記

0 での除算は inf を返します。

構文

tupleDivide(t1, t2)

引数

返される値

除算結果を格納したタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用方法

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

(0.5, 0.6666666666666666)

tupleDivideByNumber​

導入バージョン: v21.11

指定した数値で各要素を割った tuple を返します。

注記

ゼロで除算した場合は inf を返します。

構文

tupleDivideByNumber(tuple, number)

引数

戻り値

各要素を割った Tuple を返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用方法

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

導入バージョン: v1.1

タプルから要素をインデックスまたは名前で抽出します。

インデックスでアクセスする場合、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 — index が範囲外、または要素が存在しない場合に返されるデフォルト値。Any

戻り値

指定された index または name の要素を返します。Any

例

インデックスによるアクセス

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

hello

負のインデックス

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

hello

テーブルを指定した名前付きタプル

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

Alice

デフォルト値ありの場合

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

not_found

演算子の構文

SELECT (1, 'hello').2

hello

tupleHammingDistance​

導入バージョン: v21.1

要素数が同じ 2 つのタプル間のハミング距離を返します。

注記

結果の型は、入力タプル内の要素数に基づいて、Arithmetic functions と同様に決定されます。

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)

引数

戻り値

ハミング距離を返します。UInt8/16/32/64

例

使用例

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

2

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

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

2

tupleIntDiv​

導入バージョン: v23.8

分子のタプルと分母のタプルを用いて整数除算を実行します。商のタプルを返します。 いずれかのタプルに非整数要素が含まれている場合、各非整数の分子または除数は最も近い整数に丸められてから結果が計算されます。 0 による除算はエラーをスローします。

構文

tupleIntDiv(tuple_num, tuple_div)

引数

戻り値

商を要素とするタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使い方

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

(3, 2, 1)

小数を含む場合

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

(2, 1, 0)

tupleIntDivByNumber​

導入バージョン: v23.8

分子のタプルを指定された分母で整数除算し、その商をタプルとして返します。 入力パラメータのいずれかに整数以外の要素が含まれている場合、各整数以外の分子または除数は四捨五入して整数に変換したうえで結果を計算します。 0 での除算が試みられた場合はエラーがスローされます。

構文

tupleIntDivByNumber(tuple_num, div)

引数

戻り値

商のタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用例

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

(3, 2, 1)

小数を含む場合

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

(2, 1, 0)

tupleIntDivOrZero​

導入バージョン: v23.8

tupleIntDiv と同様に、分子のタプルと分母のタプルに対して整数除算を実行し、商のタプルを返します。 0 での除算が発生した場合、例外をスローする代わりに、その商を 0 として返します。 いずれかのタプルに整数以外の要素が含まれている場合は、整数以外の分子または除数ごとに最も近い整数に丸めてから結果を計算します。

構文

tupleIntDivOrZero(tuple_num, tuple_div)

引数

戻り値

商のタプルを返します。分母が 0 の要素については商として 0 を返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

分母が 0 の場合

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

(0, 0, 0)

tupleIntDivOrZeroByNumber​

導入バージョン: v23.8

tupleIntDivByNumber と同様に、分子のタプルを指定した分母で整数除算し、商のタプルを返します。 ゼロ除算の場合でもエラーはスローされず、商はゼロとして返されます。 タプルまたは分母に整数でない要素が含まれている場合、各非整数の分子または除数を最も近い整数に丸めてから結果が計算されます。

構文

tupleIntDivOrZeroByNumber(tuple_num, div)

引数

返される値

除数が 0 の要素については商を 0 とした、商のタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用例

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

(3, 2, 1)

ゼロ除算の場合

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

(0, 0, 0)

tupleMinus​

導入バージョン: v21.11

同じサイズの2つのタプルについて、対応する要素間の差を計算します。

構文

tupleMinus(t1, t2)

別名: vectorDifference

引数

戻り値

減算結果を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使い方

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

(-1, -1)

tupleModulo​

導入バージョン: v23.8

2 つのタプルの要素同士を割り算した際の余り（剰余）からなるタプルを返します。

構文

tupleModulo(tuple_num, tuple_mod)

引数

返される値

除算の剰余のタプルを返します。0 による除算が行われた場合はエラーをスローします。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使い方

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

(0, 1, 1)

tupleModuloByNumber​

導入バージョン: v23.8

タプルを指定した除数で割ったときの剰余（余り）からなるタプルを返します。

構文

tupleModuloByNumber(tuple_num, div)

引数

戻り値

各要素を除算した余りのタプルを返します。0 での除算の場合はエラーがスローされます。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用方法

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

(1, 0, 1)

tupleMultiply​

導入バージョン: v21.11

同じ長さの 2 つのタプルについて、対応する要素同士の積を計算します。

構文

tupleMultiply(t1, t2)

引数

返される値

乗算結果を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

使用例

基本的な使用方法

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

(2, 6)

tupleMultiplyByNumber​

導入: v21.11

すべての要素を与えられた数値で乗算したタプルを返します。

構文

tupleMultiplyByNumber(tuple, number)

引数

返り値

各要素を乗算したタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使い方

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

(-2.1, -4.2)

tupleNames​

導入バージョン: v

タプルをカラム名の配列に変換します。Tuple(a T, b T, ...) という形式のタプルに対して、タプル内の名前付きカラムを表す文字列の配列を返します。タプル要素に明示的な名前がない場合は、そのインデックス番号がカラム名として使用されます。

構文

引数

  • なし

返り値

例

典型的な例

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

['a','b']

tupleNegate​

導入バージョン: v21.11

タプル要素の符号反転を行います。

構文

tupleNegate(t)

引数

戻り値

符号反転した結果を含むタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使い方

SELECT tupleNegate((1, 2))

(-1, -2)

tuplePlus​

導入バージョン: v21.11

同じ長さの2つのタプルについて、対応する要素同士の合計を計算します。

構文

tuplePlus(t1, t2)

別名: vectorSum

引数

戻り値

対応する入力タプル要素同士を加算した結果を要素として持つタプルを返します。Tuple((U)Int*) または Tuple(Float*) または Tuple(Decimal)

例

基本的な使用方法

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

(3, 5)

tupleToNameValuePairs​

導入バージョン: v21.9

タプルを (name, value) ペアの配列に変換します。 たとえば、タプル Tuple(n1 T1, n2 T2, ...) は Array(Tuple('n1', T1), Tuple('n2', T2), ...) に変換されます。 タプル内のすべての値は同じ型でなければなりません。

構文

tupleToNameValuePairs(tuple)

引数

戻り値

(name, value) のペアからなる配列を返します。Array(Tuple(String, T))

例

名前付きタプル

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

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

無名タプル

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

[('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') │
└─────┴────┴────┴────┴────┴────┴───────────┘

untuple 関数の引数として Tuple 型の列を使用する例：

クエリ：

SELECT untuple(v6) FROM kv;

結果：

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

EXCEPT 式の使用例:

クエリ:

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

結果:

┌─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') │
└─────┴────┴────┴────┴───────────┘

距離関数​

サポートされている関数はすべて、距離関数のドキュメントで説明されています。