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

タプル関数

注記

以下のドキュメントは 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 つのタプルについて、対応する要素同士の除算を計算します。

注記

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

構文

tupleDivide(t1, t2)

引数

戻り値

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

例

基本的な使用方法

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

(0.5, 0.6666666666666666)

tupleDivideByNumber​

導入バージョン: v21.11

すべての要素を指定した数値で割った結果のタプルを返します。

注記

0 で割った場合は inf を返します。

構文

tupleDivideByNumber(tuple, number)

引数

戻り値

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

使用例

基本的な使い方

SELECT tupleDivideByNumber((1, 2), 0.5)

(2, 4)

tupleElement​

導入バージョン: v1.1

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

インデックスでアクセスする場合は、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

例

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

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

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 つのタプル間のハミング距離を返します。

注記

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

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はクエリのオンライン分析処理のための列指向データベース管理システムです。' 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)

除数が 0 の場合

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)

引数

戻り値

除算の余りを要素とするタプルを返します。ゼロでの除算はエラーになります。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') │
└─────┴────┴────┴────┴───────────┘

距離関数​

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