その他の関数
hostName
この関数が実行されたホスト名を返します。関数がリモートサーバー上で実行される場合（分散処理）には、リモートサーバーの名前が返されます。
関数が分散テーブルのコンテキストで実行された場合、各シャードに関連する値を持つ通常のカラムを生成します。そうでない場合は定数値を生成します。
構文
hostName()
戻り値
- ホスト名。String。
getMacro
サーバー構成のマクロセクションから名前付きの値を返します。
構文
getMacro(name);
引数
name—<macros>セクションから取得するマクロ名。String。
戻り値
- 指定されたマクロの値。String。
例
サーバー構成ファイル内の<macros>セクションの例：
<macros>
<test>Value</test>
</macros>
クエリ：
SELECT getMacro('test');
結果：
┌─getMacro('test')─┐
│ Value │
└──────────────────┘
同じ値を以下のクエリでも取得できます：
SELECT * FROM system.macros
WHERE macro = 'test';
┌─macro─┬─substitution─┐
│ test │ Value │
└───────┴──────────────┘
fqdn
ClickHouseサーバーの完全修飾ドメイン名を返します。
構文
fqdn();
別名: fullHostName, FQDN.
戻り値
- 完全修飾ドメイン名の文字列。String。
例
SELECT FQDN();
結果：
┌─FQDN()──────────────────────────┐
│ clickhouse.ru-central1.internal │
└─────────────────────────────────┘
basename
文字列の最後のスラッシュまたはバックスラッシュの後ろの部分を抽出します。この関数は通常、パスからファイル名を抽出するのに使用されます。
basename(expr)
引数
expr— String型の値。バックスラッシュはエスケープする必要があります。
戻り値
入力文字列の最後のスラッシュまたはバックスラッシュの後の部分を含む文字列。入力文字列がスラッシュまたはバックスラッシュで終わっている場合（例：/やc:\）、関数は空の文字列を返します。スラッシュやバックスラッシュがない場合は元の文字列を返します。
例
クエリ：
SELECT 'some/long/path/to/file' AS a, basename(a)
結果：
┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file │
└────────────────────────┴────────────────────────────────────────┘
クエリ：
SELECT 'some\\long\\path\\to\\file' AS a, basename(a)
結果：
┌─a──────────────────────┬─basename('some\\long\\path\\to\\file')─┐
│ some\long\path\to\file │ file │
└────────────────────────┴────────────────────────────────────────┘
クエリ：
SELECT 'some-file-name' AS a, basename(a)
結果：
┌─a──────────────┬─basename('some-file-name')─┐
│ some-file-name │ some-file-name │
└────────────────┴────────────────────────────┘
visibleWidth
テキスト形式（タブ区切り）で値をコンソールに出力するときの幅をおおよそ計算します。この関数はシステムによってPrettyフォーマットを実装するために使用されます。
NULLはPrettyフォーマットでのNULLに対応する文字列として表現されます。
構文
visibleWidth(x)
例
クエリ：
SELECT visibleWidth(NULL)
結果：
┌─visibleWidth(NULL)─┐
│ 4 │
└────────────────────┘
toTypeName
渡された引数の型名を返します。
NULLが渡された場合、関数はClickHouseの内部NULL表現に対応するNullable(Nothing)型を返します。
構文
toTypeName(value)
引数
value— 任意の型の値。
戻り値
- 入力値のデータ型名。String。
例
クエリ：
SELECT toTypeName(123);
結果：
┌─toTypeName(123)─┐
│ UInt8 │
└─────────────────┘
blockSize
ClickHouseでは、ブロック（チャンク）でクエリが処理されます。この関数は、関数が呼び出されたブロックのサイズ（行数）を返します。
構文
blockSize()
例
クエリ：
DROP TABLE IF EXISTS test;
CREATE TABLE test (n UInt8) ENGINE = Memory;
INSERT INTO test
SELECT * FROM system.numbers LIMIT 5;
SELECT blockSize()
FROM test;
結果：
┌─blockSize()─┐
1. │ 5 │
2. │ 5 │
3. │ 5 │
4. │ 5 │
5. │ 5 │
└─────────────┘
byteSize
引数の非圧縮バイトサイズの推定値を返します。
構文
byteSize(argument [, ...])
引数
argument— 値。
戻り値
- メモリ内の引数のバイトサイズの推定値。UInt64。
例
String引数の場合、関数は文字列の長さ+9（終了ゼロ+長さ）を返します。
クエリ：
SELECT byteSize('string');
結果：
┌─byteSize('string')─┐
│ 15 │
└────────────────────┘
クエリ：
CREATE TABLE test
(
`key` Int32,
`u8` UInt8,
`u16` UInt16,
`u32` UInt32,
`u64` UInt64,
`i8` Int8,
`i16` Int16,
`i32` Int32,
`i64` Int64,
`f32` Float32,
`f64` Float64
)
ENGINE = MergeTree
ORDER BY key;
INSERT INTO test VALUES(1, 8, 16, 32, 64, -8, -16, -32, -64, 32.32, 64.64);
SELECT key, byteSize(u8) AS `byteSize(UInt8)`, byteSize(u16) AS `byteSize(UInt16)`, byteSize(u32) AS `byteSize(UInt32)`, byteSize(u64) AS `byteSize(UInt64)`, byteSize(i8) AS `byteSize(Int8)`, byteSize(i16) AS `byteSize(Int16)`, byteSize(i32) AS `byteSize(Int32)`, byteSize(i64) AS `byteSize(Int64)`, byteSize(f32) AS `byteSize(Float32)`, byteSize(f64) AS `byteSize(Float64)` FROM test ORDER BY key ASC FORMAT Vertical;
結果：
Row 1:
──────
key: 1
byteSize(UInt8): 1
byteSize(UInt16): 2
byteSize(UInt32): 4
byteSize(UInt64): 8
byteSize(Int8): 1
byteSize(Int16): 2
byteSize(Int32): 4
byteSize(Int64): 8
byteSize(Float32): 4
byteSize(Float64): 8
関数に複数の引数がある場合、関数はそれらのバイトサイズを累積します。
クエリ：
SELECT byteSize(NULL, 1, 0.3, '');
結果：
┌─byteSize(NULL, 1, 0.3, '')─┐
│ 19 │
└────────────────────────────┘
materialize
定数を単一の値を含む完全なカラムに変換します。完全なカラムと定数はメモリ内で異なる形で表現されます。
通常、関数は通常の引数と定数引数に対して異なるコードを実行しますが、結果は通常同じであるべきです。
この関数はこの動作をデバッグするために使用できます。
構文
materialize(x)
パラメータ
x— 定数。Constant。
戻り値
- 単一値
xを含むカラム。
例
以下の例では、countMatches関数は定数の第2引数を期待しています。この動作は、定数を完全なカラムに変換するmaterialize関数を使用してデバッグできます。この関数は定数でない引数に対してエラーを投げます。
クエリ：
SELECT countMatches('foobarfoo', 'foo');
SELECT countMatches('foobarfoo', materialize('foo'));
結果：
2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String
ignore
任意の引数を受け取り、無条件に0を返します。引数は内部的に評価され続けるため、たとえばベンチマークに役立ちます。
構文
ignore([arg1[, arg2[, ...]])
引数
- 任意の型、
NULLを含む任意の多数の引数を受け入れることができます。
戻り値
0を返します。
例
クエリ：
SELECT ignore(0, 'ClickHouse', NULL);
結果：
┌─ignore(0, 'ClickHouse', NULL)─┐
│ 0 │
└───────────────────────────────┘
sleep
クエリの実行に遅延や一時停止を導入するために使われます。主にテストやデバッグの目的で使用されます。
構文
sleep(seconds)
引数
戻り値
この関数は値を返しません。
例
SELECT sleep(2);
この関数は値を返しません。しかし、clickhouse clientで関数を実行すると、以下のような情報が表示されます：
SELECT sleep(2)
Query id: 8aa9943e-a686-45e1-8317-6e8e3a5596ac
┌─sleep(2)─┐
│ 0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.
このクエリは2秒間の一時停止の後に完了します。この間、結果は返されず、クエリは停止しているか非応答であるように見えます。
実装の詳細
sleep()関数は通常、クエリのパフォーマンスやシステムの応答性に悪影響を及ぼすため、本番環境では使用されません。しかし、以下のような場合に役立つことがあります：
- テスト：ClickHouseをテストやベンチマークする際に、遅延をシミュレーションしたり、一時停止を導入してシステムが特定の条件下でどのように動作するかを観察できます。
- デバッグ：システムの状態やクエリの実行を特定の時点で調べる必要がある場合、
sleep()を使って一時停止を導入し、関連情報を調べたり収集したりすることができます。 - シミュレーション：ネットワーク遅延や外部システム依存など、本番環境での遅延や一時停止をシミュレートしたい場合があります。
ClickHouseシステムの全体的なパフォーマンスや応答性に影響を与える可能性があるため、sleep()関数は必要な場合にのみ、慎重に使用してください。
sleepEachRow
各行の結果セットに対して指定した秒数だけクエリの実行を一時停止します。
構文
sleepEachRow(seconds)
引数
戻り値
この関数は入力値を変更せずにそのまま返します。
例
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;
┌─number─┬─sleepEachRow(0.5)─┐
│ 0 │ 0 │
│ 1 │ 0 │
│ 2 │ 0 │
│ 3 │ 0 │
│ 4 │ 0 │
└────────┴───────────────────┘
ただし、出力は各行ごとに0.5秒の遅延付きで表示されます。
sleepEachRow()関数は、主にsleep()関数と同様にテストやデバッグの目的で使用されます。
各行の処理に遅延や一時停止をシミュレーションすることができ、次のようなシナリオで役立ちます：
- テスト：特定の条件下でのClickHouseのパフォーマンスをテストまたはベンチマークする際に、
sleepEachRow()を使用して各行処理に遅延や一時停止をシミュレーションできます。 - デバッグ：各行処理時のシステムの状態やクエリの実行を確認する際に、
sleepEachRow()を使用して一時停止を挿入し、関連情報を調べたり収集したりできます。 - シミュレーション：外部システムやネットワーク遅延など、各行処理時の遅延や停止をシミュレートしたい場合があります。
sleep()関数と同様に、特に大きな結果セットを扱う場合ClickHouseシステムのパフォーマンスや応答性に大きく影響する可能性があるため、sleepEachRow()の使用には注意が必要です。
currentDatabase
現在のデータベースの名前を返します。
CREATE TABLEクエリのテーブルエンジンのパラメータでデータベースを指定する必要がある場合に便利です。
構文
currentDatabase()
戻り値
- 現在のデータベースの名前を返します。String。
例
クエリ：
SELECT currentDatabase()
結果：
┌─currentDatabase()─┐
│ default │
└───────────────────┘
currentUser
現在のユーザーの名前を返します。分散クエリの場合、クエリを開始したユーザーの名前が返されます。
構文
currentUser()
別名: user(), USER(), current_user()。別名は大文字小文字を区別しません。
戻り値
例
SELECT currentUser();
結果：
┌─currentUser()─┐
│ default │
└───────────────┘
currentSchemas
現在のデータベーススキーマの名前を含む単一要素の配列を返します。
構文
currentSchemas(bool)
別名: current_schemas.
引数
bool: ブール値。Bool。
ブール引数は無視されます。これは、PostgreSQLでの実装との互換性のために存在します。
戻り値
- 現在のデータベース名を含む単一要素の配列を返します。
例
SELECT currentSchemas(true);
結果：
['default']
isConstant
引数が定数式かどうかを返します。
定数式とはクエリ解析中、つまり実行前に結果が判明している式を指します。
例えば、リテラルに関する式は定数式です。
この関数は主に開発、デバッグ、およびデモンストレーションを目的としています。
構文
isConstant(x)
引数
x— チェックする式。
戻り値
例
クエリ：
SELECT isConstant(x + 1) FROM (SELECT 43 AS x)
結果：
┌─isConstant(plus(x, 1))─┐
│ 1 │
└────────────────────────┘
クエリ：
WITH 3.14 AS pi SELECT isConstant(cos(pi))
結果：
┌─isConstant(cos(pi))─┐
│ 1 │
└─────────────────────┘
クエリ：
SELECT isConstant(number) FROM numbers(1)
結果：
┌─isConstant(number)─┐
│ 0 │
└────────────────────┘
hasColumnInTable
データベース名、テーブル名、カラム名を定数文字列として指定すると、指定カラムが存在する場合は1、存在しない場合は0を返します。
構文
hasColumnInTable(\[‘hostname’\[, ‘username’\[, ‘password’\]\],\] ‘database’, ‘table’, ‘column’)
パラメータ
database: データベース名。文字列リテラルtable: テーブル名。文字列リテラルcolumn: カラム名。文字列リテラルhostname: チェックを行うリモートサーバーの名前。文字列リテラルusername: リモートサーバーのユーザー名。文字列リテラルpassword: リモートサーバーのパスワード。文字列リテラル
戻り値
- 指定カラムが存在する場合は
1。 - そうでない場合は
0。
実装の詳細
ネストされたデータ構造の要素の場合、関数はカラムの存在を確認します。ネストされたデータ構造そのものについては、関数は0を返します。
例
クエリ：
SELECT hasColumnInTable('system','metrics','metric')
1
SELECT hasColumnInTable('system','metrics','non-existing_column')
0
hasThreadFuzzer
スレッドファザーが有効であるかどうかを返します。テストで実行が長くなりすぎるのを防ぐために使用できます。
構文
hasThreadFuzzer();
bar
棒グラフを構築します。
bar(x, min, max, width)は、幅が(x - min)に比例し、x = maxのときにwidth文字となるバーを描画します。
引数
x— 表示するサイズ。min, max— 整数の定数。値はInt64に収まる必要があります。width— 定数の正の整数であり、分数値を指定できます。
バーはシンボルの1/8の精度で描画されます。
例：
SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600000, 20) AS bar
FROM test.hits
GROUP BY h
ORDER BY h ASC
┌──h─┬──────c─┬─bar────────────────┐
│ 0 │ 292907 │ █████████▋ │
│ 1 │ 180563 │ ██████ │
│ 2 │ 114861 │ ███▋ │
│ 3 │ 85069 │ ██▋ │
│ 4 │ 68543 │ ██▎ │
│ 5 │ 78116 │ ██▌ │
│ 6 │ 113474 │ ███▋ │
│ 7 │ 170678 │ █████▋ │
│ 8 │ 278380 │ █████████▎ │
│ 9 │ 391053 │ █████████████ │
│ 10 │ 457681 │ ███████████████▎ │
│ 11 │ 493667 │ ████████████████▍ │
│ 12 │ 509641 │ ████████████████▊ │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊ │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍ │
│ 23 │ 400397 │ █████████████▎ │
└────┴────────┴────────────────────┘
transform
要素のいくつかを他のものに明示的に定義されたマッピングに従って、値を変換します。
この関数には2つのバリエーションがあります：
transform(x, array_from, array_to, default)
x – 変換対象。
array_from – 変換する値の定数配列。
array_to – fromの値を変換するための定数配列。
default – xがfrom内のいずれの値とも等しくない場合に使用する値。
array_fromとarray_toは同じ数の要素を持っている必要があります。
シグネチャ：
xがarray_fromの要素の一つに等しい場合、関数はarray_toの対応する要素を返します。
すなわち、同じ配列インデックスの要素です。そうでない場合、defaultを返します。array_fromに複数の一致する要素が存在する場合、最初の要素に対応するものを返します。
transform(T, Array(T), Array(U), U) -> U
TとUは数値型、文字列型、またはDateやDateTime型のいずれかです。 同じ文字（TまたはU）とは、型が相互に互換性があるが、必ずしも等しいわけではないことを意味します。
例として、最初の引数がInt64型で、2番目の引数がArray(UInt16)型であることができます。
例：
SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC
┌─title─────┬──────c─┐
│ Yandex │ 498635 │
│ Google │ 229872 │
│ Other │ 104472 │
└───────────┴────────┘
transform(x, array_from, array_to)
default引数がないことを除いて他のバリエーションと類似しています。一致が見つからない場合、xが返されます。
例：
SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s,
count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10
┌─s──────────────┬───────c─┐
│ │ 2906259 │
│ www.yandex │ 867767 │
│ ███████.ru │ 313599 │
│ mail.yandex.ru │ 107147 │
│ ██████.ru │ 100355 │
│ █████████.ru │ 65040 │
│ news.yandex.ru │ 64515 │
│ ██████.net │ 59141 │
│ example.com │ 57316 │
└────────────────┴─────────┘
formatReadableDecimalSize
サイズ（バイト数）を指定すると、この関数は小数サイズを持つ読みやすいサイズを文字列として返します（KB、MBなどの単位付き）。
この関数の逆操作はparseReadableSize、parseReadableSizeOrZero、およびparseReadableSizeOrNullです。
構文
formatReadableDecimalSize(x)
例
クエリ：
SELECT
arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
formatReadableDecimalSize(filesize_bytes) AS filesize
結果：
┌─filesize_bytes─┬─filesize───┐
│ 1 │ 1.00 B │
│ 1024 │ 1.02 KB │
│ 1048576 │ 1.05 MB │
│ 192851925 │ 192.85 MB │
└────────────────┴────────────┘
formatReadableSize
サイズ（バイト数）を指定すると、この関数は読みやすく丸められたサイズを文字列として返します（KiB、MiBなどの単位付き）。
この関数の逆操作はparseReadableSize、parseReadableSizeOrZero、およびparseReadableSizeOrNullです。
構文
formatReadableSize(x)
別名: FORMAT_BYTES.
例
クエリ：
SELECT
arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
formatReadableSize(filesize_bytes) AS filesize
結果：
┌─filesize_bytes─┬─filesize───┐
│ 1 │ 1.00 B │
│ 1024 │ 1.00 KiB │
│ 1048576 │ 1.00 MiB │
│ 192851925 │ 183.92 MiB │
└────────────────┴────────────┘
formatReadableQuantity
数を指定すると、この関数は丸められた数を文字列として返します（千、百万、十億などの接尾辞付き）。
構文
formatReadableQuantity(x)
例
クエリ：
SELECT
arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
formatReadableQuantity(number) AS number_for_humans
結果：
┌─────────number─┬─number_for_humans─┐
│ 1024 │ 1.02 thousand │
│ 1234000 │ 1.23 million │
│ 4567000000 │ 4.57 billion │
│ 98765432101234 │ 98.77 trillion │
└────────────────┴───────────────────┘
formatReadableTimeDelta
秒単位の時間間隔（デルタ）を指定すると、この関数は年/月/日/時/分/秒/ミリ秒/マイクロ秒/ナノ秒として時間デルタを文字列として返します。
構文
formatReadableTimeDelta(column[, maximum_unit, minimum_unit])
引数
column— 数値の時間デルタを持つカラム。maximum_unit— 任意。最大表示単位。- 受け入れられる値：
nanoseconds,microseconds,milliseconds,seconds,minutes,hours,days,months,years. - デフォルト値：
years.
- 受け入れられる値：
minimum_unit— 任意。最小表示単位。より小さい単位は切り捨てられます。- 受け入れられる値：
nanoseconds,microseconds,milliseconds,seconds,minutes,hours,days,months,years. - 明示的に指定された値が
maximum_unitより大きい場合、例外が投げられます。 - デフォルト値：
maximum_unitがseconds以上の場合はseconds, それ以外の場合はnanoseconds.
- 受け入れられる値：
例
SELECT
arrayJoin([100, 12345, 432546534]) AS elapsed,
formatReadableTimeDelta(elapsed) AS time_delta
┌────elapsed─┬─time_delta ─────────────────────────────────────────────────────┐
│ 100 │ 1 minute and 40 seconds │
│ 12345 │ 3 hours, 25 minutes and 45 seconds │
│ 432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds │
└────────────┴─────────────────────────────────────────────────────────────────┘
SELECT
arrayJoin([100, 12345, 432546534]) AS elapsed,
formatReadableTimeDelta(elapsed, 'minutes') AS time_delta
┌────elapsed─┬─time_delta ─────────────────────────────────────────────────────┐
│ 100 │ 1 minute and 40 seconds │
│ 12345 │ 205 minutes and 45 seconds │
│ 432546534 │ 7209108 minutes and 54 seconds │
└────────────┴─────────────────────────────────────────────────────────────────┘
SELECT
arrayJoin([100, 12345, 432546534.00000006]) AS elapsed,
formatReadableTimeDelta(elapsed, 'minutes', 'nanoseconds') AS time_delta
┌────────────elapsed─┬─time_delta─────────────────────────────────────┐
│ 100 │ 1 minute and 40 seconds │
│ 12345 │ 205 minutes and 45 seconds │
│ 432546534.00000006 │ 7209108 minutes, 54 seconds and 60 nanoseconds │
└────────────────────┴────────────────────────────────────────────────┘
parseReadableSize
バイトサイズとB、KiB、KB、MiB、MBなどの単位（例：ISO/IEC 80000-13 または小数バイト単位）を含む文字列を指定すると、この関数は対応するバイト数を返します。
入力値を解析できない場合、例外がスローされます。
この関数の逆操作はformatReadableSize と formatReadableDecimalSizeです。
構文
parseReadableSize(x)
引数
x: ISO/IEC 80000-13または小数バイト単位での読みやすいサイズ (String)。
戻り値
- バイト数、最も近い整数に切り上げられる (UInt64)。
例
SELECT
arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes,
parseReadableSize(readable_sizes) AS sizes;
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
└────────────────┴─────────┘
parseReadableSizeOrNull
バイトサイズとB、KiB、KB、MiB、MBなどの単位（例：ISO/IEC 80000-13 或いは小数バイト単位）を含む文字列を指定すると、この関数は対応するバイト数を返します。
入力値を解析できない場合、NULLを返します。
この関数の逆操作はformatReadableSize とformatReadableDecimalSizeです。
構文
parseReadableSizeOrNull(x)
引数
x: ISO/IEC 80000-13或いは小数バイト単位での読みやすいサイズ (String)。
戻り値
- バイト数，最も近い整数に切り上げられる，あるいは入力を解析できない場合はNULL（Nullable(UInt64)）。
例
SELECT
arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes,
parseReadableSizeOrNull(readable_sizes) AS sizes;
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
│ invalid │ ᴺᵁᴸᴸ │
└────────────────┴─────────┘
parseReadableSizeOrZero
バイトサイズとB、KiB、KB、MiB、MBなどの単位（例：ISO/IEC 80000-13 または小数バイト単位）を含む文字列を指定すると、この関数は対応するバイト数を返します。入力値を解析できない場合、0を返します。
この関数の逆操作はformatReadableSizeとformatReadableDecimalSizeです。
構文
parseReadableSizeOrZero(x)
引数
x: ISO/IEC 80000-13または小数バイト単位での読みやすいサイズ (String)。
戻り値
- バイト数、最も近い整数に切り上げられる、または入力を解析できない場合は0 (UInt64)。
例
SELECT
arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes,
parseReadableSizeOrZero(readable_sizes) AS sizes;
┌─readable_sizes─┬───sizes─┐
│ 1 B │ 1 │
│ 1 KiB │ 1024 │
│ 3 MB │ 3000000 │
│ 5.314 KiB │ 5442 │
│ invalid │ 0 │
└────────────────┴─────────┘
parseTimeDelta
数字の連続したものと、時間の単位に似たものを解析します。
構文
parseTimeDelta(timestr)
引数
timestr— 数字の連続したものと、時間の単位に似たもの。
戻り値
- 浮動小数点数で表される秒数。
例
SELECT parseTimeDelta('11s+22min')
┌─parseTimeDelta('11s+22min')─┐
│ 1331 │
└─────────────────────────────┘
SELECT parseTimeDelta('1yr2mo')
┌─parseTimeDelta('1yr2mo')─┐
│ 36806400 │
└──────────────────────────┘
least
aとbのうち、小さい値を返します。
構文
least(a, b)
greatest
aとbのうち、大きい値を返します。
構文
greatest(a, b)
uptime
サーバーの稼働時間を秒単位で返します。
関数が分散テーブルのコンテキストで実行された場合、各シャードに関連する値を持つ通常のカラムを生成します。そうでなければ定数値を生成します。
構文
uptime()
戻り値
- 秒数の時間値。UInt32。
例
クエリ：
SELECT uptime() as Uptime;
結果：
┌─Uptime─┐
│ 55867 │
└────────┘
version
ClickHouseの現在のバージョンを以下の形式で文字列として返します：
- メジャーバージョン
- マイナーバージョン
- パッチバージョン
- 前の安定リリースからのコミット数
メジャーバージョン.マイナーバージョン.パッチバージョン.前の安定リリースからのコミット数
関数が分散テーブルのコンテキストで実行された場合、各シャードに関連する値を持つ通常のカラムを生成します。そうでなければ定数値を生成します。
構文
version()
引数
なし。
戻り値
- ClickHouseの現在バージョン。String。
実装の詳細
なし。
例
クエリ：
SELECT version()
結果：
┌─version()─┐
│ 24.2.1.1 │
└───────────┘
buildId
現在動作しているClickHouseサーバーバイナリのコンパイラによって生成されたビルドIDを返します。
分散テーブルのコンテキストで実行された場合、各シャードに関連する値を持つ通常のカラムを生成します。それ以外の場合は定数値を生成します。
構文
buildId()
blockNumber
ブロック の行を含む単調に増加するシーケンス番号を返します。
返されるブロック番号はベストエフォートベースで更新されます。つまり、完全に正確でない場合があります。
構文
blockNumber()
戻り値
- 行が存在するデータブロックのシーケンス番号。UInt64。
例
クエリ：
SELECT blockNumber()
FROM
(
SELECT *
FROM system.numbers
LIMIT 10
) SETTINGS max_block_size = 2
結果：
┌─blockNumber()─┐
│ 7 │
│ 7 │
└───────────────┘
┌─blockNumber()─┐
│ 8 │
│ 8 │
└───────────────┘
┌─blockNumber()─┐
│ 9 │
│ 9 │
└───────────────┘
┌─blockNumber()─┐
│ 10 │
│ 10 │
└───────────────┘
┌─blockNumber()─┐
│ 11 │
│ 11 │
└───────────────┘
rowNumberInBlock
各処理されたブロックに対して、現在の行の番号を返します。この番号は各ブロックで0から始まります。
構文
rowNumberInBlock()
戻り値
- データブロックの行の序数で0から始まります。UInt64。
例
クエリ：
SELECT rowNumberInBlock()
FROM
(
SELECT *
FROM system.numbers_mt
LIMIT 10
) SETTINGS max_block_size = 2
結果：
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
┌─rowNumberInBlock()─┐
│ 0 │
│ 1 │
└────────────────────┘
rowNumberInAllBlocks
rowNumberInAllBlocksによって処理された各行に対して一意の行番号を返します。返される番号は0から始まります。
構文
rowNumberInAllBlocks()
戻り値
- データブロックの行の序数で0から始まります。UInt64。
例
クエリ：
SELECT rowNumberInAllBlocks()
FROM
(
SELECT *
FROM system.numbers_mt
LIMIT 10
)
SETTINGS max_block_size = 2
結果：
┌─rowNumberInAllBlocks()─┐
│ 0 │
│ 1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 4 │
│ 5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 2 │
│ 3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 6 │
│ 7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│ 8 │
│ 9 │
└────────────────────────┘
neighbor
指定されたオフセット前または後の行を特定のカラムから取得するウィンドウ関数です。
構文
neighbor(column, offset[, default_value])
関数の結果は影響を受けるデータブロックとブロック内のデータの順序によります。
現在処理しているデータブロックの中でのみ近傍を返します。誤りやすい動作のため、関数は非推奨です。
適切なウィンドウ関数を使用してください。
neighbor()の計算中の行の順序は、ユーザーに返される行の順序と異なる場合があります。
これを防ぐためには、ORDER BYを使用してサブクエリを作成し、サブクエリの外部から関数を呼び出すことができます。
引数
column— カラム名またはスカラー式。offset—column内で現在の行から前または先の行を探す行数。Int64。default_value— 任意。オフセットがブロック境界を超えた場合の返される値。影響を受けたデータブロックの型。
戻り値
- オフセットがブロック境界を超えなければ、現在の行からオフセット距離の
columnの値。 - オフセットがブロック境界を超えるときの
columnのデフォルト値またはdefault_value（指定されている場合）。
戻り値の型は影響を受けたデータブロックの型またはデフォルト値の型です。
例
クエリ：
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;
結果：
┌─number─┬─neighbor(number, 2)─┐
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 5 │
│ 4 │ 6 │
│ 5 │ 7 │
│ 6 │ 8 │
│ 7 │ 9 │
│ 8 │ 0 │
│ 9 │ 0 │
└────────┴─────────────────────┘
クエリ：
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;
結果：
┌─number─┬─neighbor(number, 2, 999)─┐
│ 0 │ 2 │
│ 1 │ 3 │
│ 2 │ 4 │
│ 3 │ 5 │
│ 4 │ 6 │
│ 5 │ 7 │
│ 6 │ 8 │
│ 7 │ 9 │
│ 8 │ 999 │
│ 9 │ 999 │
└────────┴──────────────────────────┘
この関数は年々のメトリクス値を計算するために使用できます：
クエリ：
WITH toDate('2018-01-01') AS start_date
SELECT
toStartOfMonth(start_date + (number * 32)) AS month,
toInt32(month) % 100 AS money,
neighbor(money, -12) AS prev_year,
round(prev_year / money, 2) AS year_over_year
FROM numbers(16)
結果：
┌──────month─┬─money─┬─prev_year─┬─year_over_year─┐
│ 2018-01-01 │ 32 │ 0 │ 0 │
│ 2018-02-01 │ 63 │ 0 │ 0 │
│ 2018-03-01 │ 91 │ 0 │ 0 │
│ 2018-04-01 │ 22 │ 0 │ 0 │
│ 2018-05-01 │ 52 │ 0 │ 0 │
│ 2018-06-01 │ 83 │ 0 │ 0 │
│ 2018-07-01 │ 13 │ 0 │ 0 │
│ 2018-08-01 │ 44 │ 0 │ 0 │
│ 2018-09-01 │ 75 │ 0 │ 0 │
│ 2018-10-01 │ 5 │ 0 │ 0 │
│ 2018-11-01 │ 36 │ 0 │ 0 │
│ 2018-12-01 │ 66 │ 0 │ 0 │
│ 2019-01-01 │ 97 │ 32 │ 0.33 │
│ 2019-02-01 │ 28 │ 63 │ 2.25 │
│ 2019-03-01 │ 56 │ 91 │ 1.62 │
│ 2019-04-01 │ 87 │ 22 │ 0.25 │
└────────────┴───────┴───────────┴────────────────┘
runningDifference
データブロック内の2つの連続する行の値の差を計算します。
最初の行には0を返し、以降の行には1つ前の行との差を返します。
現在処理しているデータブロックの中でのみ差分を返します。
誤りやすい動作のため、関数は非推奨です。適切なウィンドウ関数を使用してください。
関数の結果は影響を受けるデータブロックとブロック内のデータの順序によります。
runningDifference()の計算中の行の順序は、ユーザーに返される行の順序と異なる場合があります。
これを防ぐためには、ORDER BYを使用してサブクエリを作成し、サブクエリの外部から関数を呼び出すことができます。
構文
runningDifference(x)
例
クエリ：
SELECT
EventID,
EventTime,
runningDifference(EventTime) AS delta
FROM
(
SELECT
EventID,
EventTime
FROM events
WHERE EventDate = '2016-11-24'
ORDER BY EventTime ASC
LIMIT 5
)
結果：
┌─EventID─┬───────────EventTime─┬─delta─┐
│ 1106 │ 2016-11-24 00:00:04 │ 0 │
│ 1107 │ 2016-11-24 00:00:05 │ 1 │
│ 1108 │ 2016-11-24 00:00:05 │ 0 │
│ 1109 │ 2016-11-24 00:00:09 │ 4 │
│ 1110 │ 2016-11-24 00:00:10 │ 1 │
└─────────┴─────────────────────┴───────┘
ブロックサイズが結果に影響を与えることに注意してください。
runningDifferenceの内部状態は新しいブロックごとにリセットされます。
クエリ：
SELECT
number,
runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1
結果：
┌─number─┬─diff─┐
│ 0 │ 0 │
└────────┴──────┘
┌─number─┬─diff─┐
│ 65536 │ 0 │
└────────┴──────┘
クエリ：
set max_block_size=100000 -- デフォルト値は65536です！
SELECT
number,
runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1
結果：
┌─number─┬─diff─┐
│ 0 │ 0 │
└────────┴──────┘
runningDifferenceStartingWithFirstValue
この関数はDEPRECATEDです（runningDifferenceの注釈を参照）。
最初の行の値を最初の行に返す以外は、runningDifferenceと同じです。
runningConcurrency
同時に発生するイベントの数を計算します。
各イベントには開始時間と終了時間があります。
開始時間はイベントに含まれていますが、終了時間は除外されています。列の開始時間と終了時間は同じデータ型でなければなりません。
関数は、各イベントの開始時間に対してアクティブ（並行）のイベントの総数を計算します。
イベントは開始時間で昇順に並べられている必要があります。この要件が満たされない場合、関数は例外をスローします。
すべてのデータブロックは別々に処理されます。異なるデータブロックからのイベントが重なる場合、それらは正しく処理されません。
構文
runningConcurrency(start, end)
引数
start— イベントの開始時間を持つカラム。Date, DateTime, または DateTime64。end— イベントの終了時間を持つカラム。Date, DateTime, または DateTime64。
戻り値
- 各イベントの開始時間における同時に発生しているイベントの数。UInt32
例
表は：
┌──────start─┬────────end─┐
│ 2021-03-03 │ 2021-03-11 │
│ 2021-03-06 │ 2021-03-12 │
│ 2021-03-07 │ 2021-03-08 │
│ 2021-03-11 │ 2021-03-12 │
└────────────┴────────────┘
クエリ：
SELECT start, runningConcurrency(start, end) FROM example_table;
結果：
┌──────start─┬─runningConcurrency(start, end)─┐
│ 2021-03-03 │ 1 │
│ 2021-03-06 │ 2 │
│ 2021-03-07 │ 3 │
│ 2021-03-11 │ 2 │
└────────────┴────────────────────────────────┘
MACNumToString
UInt64数値をビッグエンディアン形式のMACアドレスとして解釈します。
対応するMACアドレスをAA:BB:CC:DD:EE:FF（コロンで区切った16進数）形式で文字列として返します。
構文
MACNumToString(num)
MACStringToNum
MACNumToStringの逆関数です。MACアドレスが無効な形式の場合、0を返します。
構文
MACStringToNum(s)
MACStringToOUI
MACアドレスをAA:BB:CC:DD:EE:FF（コロンで区切った16進数）形式で指定すると、最初の3オクテットをUInt64数値として返します。
MACアドレスが無効な形式の場合、0を返します。
構文
MACStringToOUI(s)
getSizeOfEnumType
Enum型のフィールドの数を返します。
型がEnumでない場合、例外がスローされます。
構文
getSizeOfEnumType(value)
引数:
value—Enum型の値。
戻り値
Enum型入力値のフィールド数を返します。
例
SELECT getSizeOfEnumType( CAST('a' AS Enum8('a' = 1, 'b' = 2) ) ) AS x
┌─x─┐
│ 2 │
└───┘
blockSerializedSize
圧縮を考慮せずにディスク上のサイズを返します。
blockSerializedSize(value[, value[, ...]])
引数
value— 任意の値。
戻り値
- ブロックの値を書き込むためにディスクに書き込まれるバイト数を返します。ただし、圧縮を考慮しません。
例
クエリ：
SELECT blockSerializedSize(maxState(1)) as x
結果：
┌─x─┐
│ 2 │
└───┘
toColumnTypeName
値を表しているデータ型の内部名を返します。
構文
toColumnTypeName(value)
引数:
value— 任意の型の値。
戻り値
valueを表すために使用される内部データ型名。
例
toTypeNameとtoColumnTypeNameの違い:
SELECT toTypeName(CAST('2018-01-01 01:02:03' AS DateTime))
結果：
┌─toTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime │
└─────────────────────────────────────────────────────┘
クエリ：
SELECT toColumnTypeName(CAST('2018-01-01 01:02:03' AS DateTime))
結果：
┌─toColumnTypeName(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32) │
└───────────────────────────────────────────────────────────┘
例はDateTimeデータ型が内部的にConst(UInt32)として格納されていることを示しています。
dumpColumnStructure
RAM内のデータ構造の詳細な説明を出力します。
dumpColumnStructure(value)
引数:
value— 任意の型の値。
戻り値
valueを表すために使用されるカラム構造の説明。
例
SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))
┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1)) │
└──────────────────────────────────────────────────────────────┘
defaultValueOfArgumentType
指定されたデータ型に対するデフォルト値を返します。
ユーザーが設定したカスタムカラムのデフォルト値は含まれません。
構文
defaultValueOfArgumentType(expression)
引数:
expression— 任意の型か任意の型の値を結果とする式。
戻り値
- 数値の場合は
0。 - 文字列の場合は空文字列。
- Nullableの場合は
ᴺᵁᴸᴸ。
例
クエリ：
SELECT defaultValueOfArgumentType( CAST(1 AS Int8) )
結果：
┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│ 0 │
└─────────────────────────────────────────────┘
クエリ：
SELECT defaultValueOfArgumentType( CAST(1 AS Nullable(Int8) ) )
結果：
┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│ ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘
defaultValueOfTypeName
指定された型名に対するデフォルト値を返します。
ユーザーが設定したカスタムカラムのデフォルト値は含まれません。
defaultValueOfTypeName(type)
引数:
type— 型名を表す文字列。
戻り値
- 数値の場合は
0。 - 文字列の場合は空文字列。
- Nullableの場合は
ᴺᵁᴸᴸ。
例
クエリ：
SELECT defaultValueOfTypeName('Int8')
結果：
┌─defaultValueOfTypeName('Int8')─┐
│ 0 │
└────────────────────────────────┘
クエリ：
SELECT defaultValueOfTypeName('Nullable(Int8)')
結果：
┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│ ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘
indexHint
この関数はデバッグとイントロスペクションを目的としています。引数を無視して常に1を返します。引数は評価されません。
ただし、インデックス分析中にこの関数の引数はindexHintでラップされていないと仮定されます。
これにより、対応する条件でインデックス範囲のデータを選択できますが、その条件によるさらなるフィルタリングは行いません。ClickHouseのインデックスはスパースであり、indexHintを使用すると、同じ条件を直接指定した場合よりも多くのデータが得られます。
構文
SELECT * FROM table WHERE indexHint(<expression>)
戻り値
1。Uint8。
例
次は、テーブルontimeのテストデータの例です。
テーブル：
SELECT count() FROM ontime
┌─count()─┐
│ 4276457 │
└─────────┘
テーブルはフィールド(FlightDate, (Year, FlightDate))にインデックスを持っています。
インデックスを使用しないクエリを作成します：
SELECT FlightDate AS k, count() FROM ontime GROUP BY k ORDER BY k
ClickHouseはテーブル全体を処理します（約428万行処理済み）。
結果：
┌──────────k─┬─count()─┐
│ 2017-01-01 │ 13970 │
│ 2017-01-02 │ 15882 │
........................
│ 2017-09-28 │ 16411 │
│ 2017-09-29 │ 16384 │
│ 2017-09-30 │ 12520 │
└────────────┴─────────┘
インデックスを適用するには、特定の日付を選択します：
SELECT FlightDate AS k, count() FROM ontime WHERE k = '2017-09-15' GROUP BY k ORDER BY k
ClickHouse現在ではインデックスを利用し、はるかに少ない行数（32,740行処理済み）を処理します。
結果：
┌──────────k─┬─count()─┐
│ 2017-09-15 │ 16428 │
└────────────┴─────────┘
今、式k = '2017-09-15'を関数indexHintでラップします：
クエリ：
SELECT
FlightDate AS k,
count()
FROM ontime
WHERE indexHint(k = '2017-09-15')
GROUP BY k
ORDER BY k ASC
ClickHouseは前回と同様にインデックスを使用しました（32,740行処理済み）。
結果を生成する際にk = '2017-09-15'の式は使用されませんでした。例では、indexHint関数を使用して隣接する日付を確認できます。
結果：
┌──────────k─┬─count()─┐
│ 2017-09-14 │ 7071 │
│ 2017-09-15 │ 16428 │
│ 2017-09-16 │ 1077 │
│ 2017-09-30 │ 8167 │
└────────────┴─────────┘
replicate
単一の値を持つ配列を作成します。
この関数は配列結合の内部実装に使用されます。
構文
replicate(x, arr)
引数
x— 結果配列を埋める値。arr— 配列。Array。
戻り値
arrと同じ長さで値xで満たされた配列。Array。
例
クエリ：
SELECT replicate(1, ['a', 'b', 'c']);
結果：
┌─replicate(1, ['a', 'b', 'c'])─┐
│ [1,1,1] │
└───────────────────────────────┘
revision
現在のClickHouse サーバリビジョンを返します。
構文
revision()
戻り値
- 現在のClickHouseサーバーリビジョン。UInt32。
例
クエリ：
SELECT revision();
結果：
┌─revision()─┐
│ 54485 │
└────────────┘
filesystemAvailable
データベースの永続化をホスティングしているファイルシステムの空きスペースを返します。返される値は、オペレーティングシステムのために予約されているため、常に合計の空きスペース (filesystemFree) よりも小さくなります。
構文
filesystemAvailable()
返り値
- バイト単位での残りの空きスペースの量です。UInt64。
例
クエリ:
SELECT formatReadableSize(filesystemAvailable()) AS "Available space";
結果:
┌─Available space─┐
│ 30.75 GiB │
└─────────────────┘
filesystemUnreserved
データベースの永続化をホスティングしているファイルシステムの合計空きスペースを返します。（以前は filesystemFree）。filesystemAvailable も参照してください。
構文
filesystemUnreserved()
返り値
- 空きスペースの量（バイト単位）です。UInt64。
例
クエリ:
SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";
結果:
┌─Free space─┐
│ 32.39 GiB │
└────────────┘
filesystemCapacity
ファイルシステムの容量をバイト単位で返します。データディレクトリのパスを設定する必要があります。
構文
filesystemCapacity()
返り値
- バイト単位でのファイルシステムの容量。UInt64。
例
クエリ:
SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";
結果:
┌─Capacity──┐
│ 39.32 GiB │
└───────────┘
initializeAggregation
単一の値に基づいて集計関数の結果を計算します。この関数は、-State コンビネータを使用して集計関数を初期化するために使用できます。集計関数の状態を作成し、それらを AggregateFunction 型のカラムに挿入するか、初期化された集計をデフォルト値として使用できます。
構文
initializeAggregation (aggregate_function, arg1, arg2, ..., argN)
引数
aggregate_function— 初期化する集計関数の名前。String。arg— 集計関数の引数。
返り値
- 関数に渡された各行に対する集計の結果。
返り値の型は、最初の引数として initializeAggregation が取る関数の返り値の型と同じです。
例
クエリ:
SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));
結果:
┌─uniqMerge(state)─┐
│ 3 │
└──────────────────┘
クエリ:
SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));
結果:
┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│ 0 │ AggregateFunction(sum, UInt8) │
│ 1 │ AggregateFunction(sum, UInt8) │
│ 2 │ AggregateFunction(sum, UInt8) │
│ 0 │ AggregateFunction(sum, UInt8) │
│ 1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘
AggregatingMergeTree テーブルエンジンと AggregateFunction カラムを使用した例:
CREATE TABLE metrics
(
key UInt64,
value AggregateFunction(sum, UInt64) DEFAULT initializeAggregation('sumState', toUInt64(0))
)
ENGINE = AggregatingMergeTree
ORDER BY key
INSERT INTO metrics VALUES (0, initializeAggregation('sumState', toUInt64(42)))
関連情報
finalizeAggregation
集計関数の状態を与えると、この関数は集計の結果（または -State コンビネータを使用する際の最終化された状態）を返します。
構文
finalizeAggregation(state)
引数
state— 集計の状態。AggregateFunction。
返り値
- 集計された値/値。
返り値の型は集計された任意の型と等しいです。
例
クエリ:
SELECT finalizeAggregation(( SELECT countState(number) FROM numbers(10)));
結果:
┌─finalizeAggregation(_subquery16)─┐
│ 10 │
└──────────────────────────────────┘
クエリ:
SELECT finalizeAggregation(( SELECT sumState(number) FROM numbers(10)));
結果:
┌─finalizeAggregation(_subquery20)─┐
│ 45 │
└──────────────────────────────────┘
NULL 値は無視されることに注意してください。
クエリ:
SELECT finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]));
結果:
┌─finalizeAggregation(arrayReduce('anyState', [NULL, 2, 3]))─┐
│ 2 │
└────────────────────────────────────────────────────────────┘
複合的な例:
クエリ:
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
number,
finalizeAggregation(one_row_sum_state) AS one_row_sum,
runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(10);
結果:
┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│ 0 │ 0 │ 0 │
│ 1 │ 1 │ 1 │
│ 2 │ 2 │ 3 │
│ 3 │ 3 │ 6 │
│ 4 │ 4 │ 10 │
│ 5 │ 5 │ 15 │
│ 6 │ 6 │ 21 │
│ 7 │ 7 │ 28 │
│ 8 │ 8 │ 36 │
│ 9 │ 9 │ 45 │
└────────┴─────────────┴────────────────┘
関連情報
runningAccumulate
データブロックの各行に対する集計関数の状態を累積します。
状態は新しいデータブロックごとにリセットされます。 この誤りやすい動作のため、この関数は推奨されません。代わりに適切なウィンドウ関数を使用してください。
構文
runningAccumulate(agg_state[, grouping]);
引数
agg_state— 集計関数の状態。AggregateFunction。grouping— グルーピングキー。オプション。groupingの値が変わると関数の状態がリセットされます。サポートされているデータ型の中で等価演算子が定義されているものを使用できます。
返り値
- 結果の各行には、入力行の0から現在の位置までのすべての行に対する集計関数の結果が含まれます。
runningAccumulateは、各新しいデータブロックまたはgrouping値が変わったときに状態をリセットします。
型は使用された集計関数に依存します。
例
グルーピングを使用せずに数値の累積合計を求める方法と、グルーピングを使用する方法を考えてみます。
クエリ:
SELECT k, runningAccumulate(sum_k) AS res FROM (SELECT number as k, sumState(k) AS sum_k FROM numbers(10) GROUP BY k ORDER BY k);
結果:
┌─k─┬─res─┐
│ 0 │ 0 │
│ 1 │ 1 │
│ 2 │ 3 │
│ 3 │ 6 │
│ 4 │ 10 │
│ 5 │ 15 │
│ 6 │ 21 │
│ 7 │ 28 │
│ 8 │ 36 │
│ 9 │ 45 │
└───┴─────┘
サブクエリは、0 から 9 までの各数値に関して sumState を生成します。sumState は、単一の数の合計を含む sum 関数の状態を返します。
全体のクエリは次のことを行います:
- 最初の行では、
runningAccumulateはsumState(0)を取得し0を返します。 - 2番目の行では、関数は
sumState(0)とsumState(1)をマージし、sumState(0 + 1)を生成し、結果として1を返します。 - 3番目の行では、関数は
sumState(0 + 1)とsumState(2)をマージし、sumState(0 + 1 + 2)を生成し、結果として3を返します。 - ブロックが終了するまでこれらの操作が繰り返されます。
以下の例は、grouping パラメータの使用法を示しています:
クエリ:
SELECT
grouping,
item,
runningAccumulate(state, grouping) AS res
FROM
(
SELECT
toInt8(number / 4) AS grouping,
number AS item,
sumState(number) AS state
FROM numbers(15)
GROUP BY item
ORDER BY item ASC
);
結果:
┌─grouping─┬─item─┬─res─┐
│ 0 │ 0 │ 0 │
│ 0 │ 1 │ 1 │
│ 0 │ 2 │ 3 │
│ 0 │ 3 │ 6 │
│ 1 │ 4 │ 4 │
│ 1 │ 5 │ 9 │
│ 1 │ 6 │ 15 │
│ 1 │ 7 │ 22 │
│ 2 │ 8 │ 8 │
│ 2 │ 9 │ 17 │
│ 2 │ 10 │ 27 │
│ 2 │ 11 │ 38 │
│ 3 │ 12 │ 12 │
│ 3 │ 13 │ 25 │
│ 3 │ 14 │ 39 │
└──────────┴──────┴─────┘
ご覧のとおり、runningAccumulate は各行のグループごとに状態を結合します。
joinGet
関数はDictionaryのようにテーブルからデータを抽出します。指定された結合キーを使用してJoinテーブルからデータを取得します。
ENGINE = Join(ANY, LEFT, <join_keys>) ステートメントで作成されたテーブルのみをサポートします。
構文
joinGet(join_storage_table_name, `value_column`, join_keys)
引数
join_storage_table_name— 検索が実行される場所を示す識別子。value_column— 必要なデータが含まれるテーブルのカラム名。join_keys— キーのリスト。
識別子はデフォルトデータベース（コンフィグファイルの default_database 設定を参照）で検索されます。デフォルトデータベースを上書きするためには、USE db_nameまたはdb_name.db_tableの形式でデータベースとテーブルを指定します。
返り値
- キーのリストに対応する値のリストを返します。
あるキーがソーステーブルに存在しない場合、テーブル作成時のjoin_use_nulls設定に基づいて0またはnullが返されます。
join_use_nullsの詳細についてはJoin operationを参照してください。
例
入力テーブル:
CREATE DATABASE db_test;
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
クエリ:
SELECT number, joinGet(db_test.id_val, 'val', toUInt32(number)) from numbers(4);
結果:
┌─number─┬─joinGet('db_test.id_val', 'val', toUInt32(number))─┐
1. │ 0 │ 0 │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ 0 │
└────────┴────────────────────────────────────────────────────┘
join_use_nulls を使用して、ソーステーブルにキーが存在しない場合に返される動作を変更できます。
CREATE DATABASE db_test;
CREATE TABLE db_test.id_val_nulls(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id) SETTINGS join_use_nulls=1;
INSERT INTO db_test.id_val_nulls VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val_nulls;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
クエリ:
SELECT number, joinGet(db_test.id_val_nulls, 'val', toUInt32(number)) from numbers(4);
結果:
┌─number─┬─joinGet('db_test.id_val_nulls', 'val', toUInt32(number))─┐
1. │ 0 │ ᴺᵁᴸᴸ │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘
joinGetOrNull
joinGet と同様ですが、キーが見つからない場合にはデフォルト値を返す代わりに NULL を返します。
構文
joinGetOrNull(join_storage_table_name, `value_column`, join_keys)
引数
join_storage_table_name— 検索が実行される場所を示す識別子。value_column— 必要なデータが含まれるテーブルのカラム名。join_keys— キーのリスト。
識別子はデフォルトデータベース（コンフィグファイルの default_database 設定を参照）で検索されます。デフォルトデータベースを上書きするためには、USE db_nameまたはdb_name.db_tableの形式でデータベースとテーブルを指定します。
返り値
- キーのリストに対応する値のリストを返します。
ソーステーブルに特定のキーが存在しない場合、そのキーに対して NULL が返されます。
例
入力テーブル:
CREATE DATABASE db_test;
CREATE TABLE db_test.id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO db_test.id_val VALUES (1, 11)(2, 12)(4, 13);
SELECT * FROM db_test.id_val;
┌─id─┬─val─┐
│ 4 │ 13 │
│ 2 │ 12 │
│ 1 │ 11 │
└────┴─────┘
クエリ:
SELECT number, joinGetOrNull(db_test.id_val, 'val', toUInt32(number)) from numbers(4);
結果:
┌─number─┬─joinGetOrNull('db_test.id_val', 'val', toUInt32(number))─┐
1. │ 0 │ ᴺᵁᴸᴸ │
2. │ 1 │ 11 │
3. │ 2 │ 12 │
4. │ 3 │ ᴺᵁᴸᴸ │
└────────┴──────────────────────────────────────────────────────────┘
catboostEvaluate
この関数は ClickHouse Cloud では利用できません。
外部の catboost モデルを評価します。CatBoost は、Yandex により開発された機械学習のためのオープンソースの勾配ブースティングライブラリです。 catboost モデルへのパスとモデルの引数（特徴量）を受け取り、Float64 を返します。
構文
catboostEvaluate(path_to_model, feature_1, feature_2, ..., feature_n)
例
SELECT feat1, ..., feat_n, catboostEvaluate('/path/to/model.bin', feat_1, ..., feat_n) AS prediction
FROM data_table
前提条件
- catboost 評価ライブラリをビルドする
catboost モデルを評価する前に、libcatboostmodel.<so|dylib> ライブラリを利用可能にする必要があります。コンパイル方法については CatBoost ドキュメンテーション を参照してください。
次に、clickhouse 設定に libcatboostmodel.<so|dylib> のパスを指定してください:
<clickhouse>
...
<catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>
セキュリティおよび隔離のため、モデル評価はサーバープロセスではなく clickhouse-library-bridge プロセスで実行されます。
catboostEvaluate() の最初の実行時に、サーバーは library bridge プロセスがすでに実行されていない場合にこれを開始します。両プロセスは HTTP インターフェースを使用して通信します。デフォルトでは、ポート 9012 が使用されます。ポート 9012 が他のサービスに割り当てられている場合に別のポートを指定することができます。
<library_bridge>
<port>9019</port>
</library_bridge>
- libcatboost を使用した catboost モデルのトレーニング
トレーニングデータセットから catboost モデルをトレーニングする方法については、モデルのトレーニングと適用を参照してください。
throwIf
引数 x が正しければ例外をスローします。
構文
throwIf(x[, message[, error_code]])
引数
x- チェックする条件。message- カスタムエラーメッセージを提供する定数文字列。オプション。error_code- カスタムエラーコードを提供する定数整数。オプション。
error_code 引数を使用するには、構成パラメータ allow_custom_error_code_in_throwif を有効にする必要があります。
例
SELECT throwIf(number = 3, 'Too many') FROM numbers(10);
結果:
↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.
identity
引数をそのまま返します。デバッグおよびテストを目的とします。インデックスを使わないことや全検索のクエリ実行性能を得ることができます。クエリがインデックスの使用可能性について分析される際に、分析者は identity 関数内のすべてのものを無視します。また、定数展開を無効にします。
構文
identity(x)
例
クエリ:
SELECT identity(42);
結果:
┌─identity(42)─┐
│ 42 │
└──────────────┘
getSetting
カスタム設定の現在の値を返します。
構文
getSetting('custom_setting');
パラメータ
custom_setting— 設定名。String。
返り値
- 設定の現在の値。
例
SET custom_a = 123;
SELECT getSetting('custom_a');
結果:
123
関連情報
getSettingOrDefault
カスタム設定の現在の値またはカスタム設定が現在のプロファイルに設定されていない場合に第2引数で指定されたデフォルト値を返します。
構文
getSettingOrDefault('custom_setting', default_value);
パラメータ
custom_setting— 設定名。String。default_value— カスタム設定が設定されていない場合に返される値。任意のデータ型または Null の値となる可能性があります。
返り値
- 設定の現在の値または設定されていない場合の default_value。
例
SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);
結果:
my_value
100
NULL
関連情報
isDecimalOverflow
Decimal 値がその精度を超えているか、指定された精度を超えているかどうかをチェックします。
構文
isDecimalOverflow(d, [p])
引数
返り値
1— Decimal 値がその精度によって許可される桁数を超えていること。0— Decimal 値が指定された精度を満たしていること。
例
クエリ:
SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
isDecimalOverflow(toDecimal32(1000000000, 0)),
isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
isDecimalOverflow(toDecimal32(-1000000000, 0));
結果:
1 1 1 1
countDigits
値を表現するのに必要な10進数の桁数を返します。
構文
countDigits(x)
引数
返り値
- 桁数。UInt8。
Decimal 値はそれらのスケールを考慮します: その基礎となる整数型 value * scale を計算します。例えば：countDigits(42) = 2, countDigits(42.000) = 5, countDigits(0.04200) = 4。つまり、Decimal64 の小数点オーバーフローを countDigits(x) > 18 でチェックできます。これは isDecimalOverflow の遅いバリアントです。
例
クエリ:
SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));
結果:
10 10 19 19 39 39
errorCodeToName
- エラーコードのテキスト名。LowCardinality(String)。
構文
errorCodeToName(1)
結果:
UNSUPPORTED_METHOD
tcpPort
このサーバーによってリッスンされているnative インターフェースの TCP ポート番号を返します。 分散テーブルのコンテキストで実行される場合、この関数は各シャードに関連する通常のカラムを生成します。それ以外の場合、定数値を生成します。
構文
tcpPort()
引数
- なし。
返り値
- TCP ポート番号。UInt16。
例
クエリ:
SELECT tcpPort();
結果:
┌─tcpPort()─┐
│ 9000 │
└───────────┘
関連情報
currentProfiles
現在のユーザーの設定プロファイルのリストを返します。
現在の設定プロファイルを変更するには、SET PROFILE コマンドを使用できます。SET PROFILE コマンドが使用されていない場合、この関数は現在のユーザー定義で指定されたプロファイルを返します（CREATE USER 参照）。
構文
currentProfiles()
返り値
enabledProfiles
明示的および暗黙的に現在のユーザーに割り当てられた設定プロファイルを返します。明示的に割り当てられたプロファイルは currentProfiles 関数によって返されるものと同じです。暗黙的に割り当てられたプロファイルには、他の割り当てられたプロファイル、付与されたロールを介して割り当てられたプロファイル、それ自体の設定を介して割り当てられたプロファイル、メインデフォルトプロファイル（メインサーバー設定ファイルの default_profile セクション参照）の親プロファイルが含まれます。
構文
enabledProfiles()
返り値
defaultProfiles
現在のユーザー定義で指定されたすべてのプロファイルを返します（CREATE USER ステートメント参照）。
構文
defaultProfiles()
返り値
currentRoles
現在のユーザーに割り当てられたロールを返します。ロールは SET ROLE ステートメントによって変更することができます。SET ROLE ステートメントが利用されていない場合、関数 currentRoles は defaultRoles と同じものを返します。
構文
currentRoles()
返り値
enabledRoles
現在のロールと現在のロールに付与されたロールの名前を返します。
構文
enabledRoles()
返り値
defaultRoles
ログイン時に現在のユーザーに対してデフォルトで有効にされるロールを返します。これらは通常、現在のユーザーに付与されたすべてのロールですが（GRANT 参照）、SET DEFAULT ROLE ステートメントで変更することができます。
構文
defaultRoles()
返り値
getServerPort
サーバーのポート番号を返します。ポートがサーバーによって使用されていない場合、例外をスローします。
構文
getServerPort(port_name)
引数
port_name— サーバーポート名。String。可能な値:- 'tcp_port'
- 'tcp_port_secure'
- 'http_port'
- 'https_port'
- 'interserver_http_port'
- 'interserver_https_port'
- 'mysql_port'
- 'postgresql_port'
- 'grpc_port'
- 'prometheus.port'
返り値
- サーバーポートの番号。UInt16。
例
クエリ:
SELECT getServerPort('tcp_port');
結果:
┌─getServerPort('tcp_port')─┐
│ 9000 │
└───────────────────────────┘
queryID
現在のクエリの ID を返します。他のクエリのパラメータは、query_id を使用して system.query_log テーブルから取得できます。
initialQueryID 関数とは異なり、queryID は異なるシャードで異なる結果を返すことができます。（例を参照）
構文
queryID()
返り値
- 現在のクエリの ID。String
例
クエリ:
CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
結果:
┌─count()─┐
│ 3 │
└─────────┘
initialQueryID
初期の現在のクエリの ID を返します。他のクエリのパラメータは、initial_query_id を使用して system.query_log テーブルから取得できます。
queryID 関数とは異なり、initialQueryID は異なるシャードで同じ結果を返します。（例を参照）
構文
initialQueryID()
返り値
- 初期の現在のクエリの ID。String
例
クエリ:
CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());
結果:
┌─count()─┐
│ 1 │
└─────────┘
partitionID
パーティション IDを計算します。
この関数は遅いため、多数の行に対して呼び出すべきではありません。
構文
partitionID(x[, y, ...]);
引数
x— パーティション ID を返すカラム。y, ...— パーティション ID を返す残りの N 個のカラム（オプション）。
返り値
- 行が属するパーティション ID。String。
例
クエリ:
DROP TABLE IF EXISTS tab;
CREATE TABLE tab
(
i int,
j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();
INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);
SELECT i, j, partitionID(i), _partition_id FROM tab ORDER BY i, j;
結果:
┌─i─┬─j─┬─partitionID(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1 │ 1 │
│ 1 │ 2 │ 1 │ 1 │
│ 1 │ 3 │ 1 │ 1 │
└───┴───┴────────────────┴───────────────┘
┌─i─┬─j─┬─partitionID(i)─┬─_partition_id─┐
│ 2 │ 4 │ 2 │ 2 │
│ 2 │ 5 │ 2 │ 2 │
│ 2 │ 6 │ 2 │ 2 │
└───┴───┴────────────────┴───────────────┘
shardNum
分散クエリで分散テーブルのデータの一部を処理するシャードのインデックスを返します。インデックスは 1 から始まります。
クエリが分散されていない場合、定数値 0 が返されます。
構文
shardNum()
返り値
- シャードインデックスまたは定数
0。UInt32。
例
以下の例では、2つのシャードを使用した構成を使用します。クエリは各シャードの system.one テーブルで実行されます。
クエリ:
CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;
結果:
┌─dummy─┬─shardNum()─┬─shardCount()─┐
│ 0 │ 2 │ 2 │
│ 0 │ 1 │ 2 │
└───────┴────────────┴──────────────┘
関連情報
shardCount
分散クエリに対するシャードの総数を返します。
クエリが分散されていない場合、定数 0 が返されます。
構文
shardCount()
返り値
- シャードの総数または
0。UInt32。
関連情報
- shardNum() 関数の例にも
shardCount()関数呼び出しが含まれています。
getOSKernelVersion
現在の OS カーネルバージョンを文字列で返します。
構文
getOSKernelVersion()
引数
- なし。
返り値
- 現在の OS カーネルバージョン。String。
例
クエリ:
SELECT getOSKernelVersion();
結果:
┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘
zookeeperSessionUptime
現在の ZooKeeper セッションのアップタイムを秒単位で返します。
構文
zookeeperSessionUptime()
引数
- なし。
返り値
- 現在の ZooKeeper セッションのアップタイム（秒単位）。UInt32。
例
クエリ:
SELECT zookeeperSessionUptime();
結果:
┌─zookeeperSessionUptime()─┐
│ 286 │
└──────────────────────────┘
generateRandomStructure
テーブル構造を column1_name column1_type, column2_name column2_type, ... の形式でランダムに生成します。
構文
generateRandomStructure([number_of_columns, seed])
引数
number_of_columns— 結果のテーブル構造での希望するカラム数。0 またはNullに設定した場合、1 から 128 の範囲でランダムのカラム数になります。デフォルト値:Null。seed- 安定した結果を生成するためのランダムシード。シードが指定されていないかNullに設定されている場合、ランダムに生成されます。
すべての引数は定数でなければなりません。
返り値
- ランダムに生成されたテーブル構造。String。
例
クエリ:
SELECT generateRandomStructure()
結果:
┌─generateRandomStructure()─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
クエリ:
SELECT generateRandomStructure(1)
結果:
┌─generateRandomStructure(1)─┐
│ c1 Map(UInt256, UInt16) │
└────────────────────────────┘
クエリ:
SELECT generateRandomStructure(NULL, 33)
結果:
┌─generateRandomStructure(NULL, 33)─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70))) │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
注: 複雑な型（Array、Tuple、Map、Nested）の最大ネスト深度は 16 に制限されています。
この関数は、generateRandom と一緒に使用して完全にランダムなテーブルを生成することができます。
structureToCapnProtoSchema
ClickHouse のテーブル構造を CapnProto スキーマに変換します。
構文
structureToCapnProtoSchema(structure)
引数
structure—column1_name column1_type, column2_name column2_type, ...の形式でのテーブル構造。root_struct_name— CapnProto スキーマのルート構造の名前。デフォルト値 -Message;
返り値
- CapnProto スキーマ。String。
例
クエリ:
SELECT structureToCapnProtoSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB
結果:
@0xf96402dd754d0eb7;
struct Message
{
column1 @0 : Data;
column2 @1 : UInt32;
column3 @2 : List(Data);
}
クエリ:
SELECT structureToCapnProtoSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB
結果:
@0xd1c8320fecad2b7f;
struct Message
{
struct Column1
{
union
{
value @0 : Data;
null @1 : Void;
}
}
column1 @0 : Column1;
struct Column2
{
element1 @0 : UInt32;
element2 @1 : List(Data);
}
column2 @1 : Column2;
struct Column3
{
struct Entry
{
key @0 : Data;
value @1 : Data;
}
entries @0 : List(Entry);
}
column3 @2 : Column3;
}
クエリ:
SELECT structureToCapnProtoSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB
結果:
@0x96ab2d4ab133c6e1;
struct Root
{
column1 @0 : Data;
column2 @1 : UInt32;
}
structureToProtobufSchema
ClickHouse のテーブル構造を Protobuf スキーマに変換します。
構文
structureToProtobufSchema(structure)
引数
structure—column1_name column1_type, column2_name column2_type, ...の形式でのテーブル構造。root_message_name— Protobuf スキーマのルートメッセージの名前。デフォルト値 -Message;
返り値
- Protobuf スキーマ。String。
例
クエリ:
SELECT structureToProtobufSchema('column1 String, column2 UInt32, column3 Array(String)') FORMAT RawBLOB
結果:
syntax = "proto3";
message Message
{
bytes column1 = 1;
uint32 column2 = 2;
repeated bytes column3 = 3;
}
クエリ:
SELECT structureToProtobufSchema('column1 Nullable(String), column2 Tuple(element1 UInt32, element2 Array(String)), column3 Map(String, String)') FORMAT RawBLOB
結果:
syntax = "proto3";
message Message
{
bytes column1 = 1;
message Column2
{
uint32 element1 = 1;
repeated bytes element2 = 2;
}
Column2 column2 = 2;
map<string, bytes> column3 = 3;
}
クエリ:
SELECT structureToProtobufSchema('column1 String, column2 UInt32', 'Root') FORMAT RawBLOB
結果:
syntax = "proto3";
message Root
{
bytes column1 = 1;
uint32 column2 = 2;
}
formatQuery
与えられた SQL クエリのフォーマットされた（複数行を含む可能性のある）バージョンを返します。
クエリが構文的に正しくない場合、例外をスローします。代わりに NULL を返すには、formatQueryOrNull() 関数を使用してください。
構文
formatQuery(query)
formatQueryOrNull(query)
引数
query- フォーマット対象の SQL クエリ。String
返り値
- フォーマットされたクエリ。String。
例
SELECT formatQuery('select a, b FRom tab WHERE a > 3 and b < 3');
結果:
┌─formatQuery('select a, b FRom tab WHERE a > 3 and b < 3')─┐
│ SELECT
a,
b
FROM tab
WHERE (a > 3) AND (b < 3) │
└───────────────────────────────────────────────────────────────┘
formatQuerySingleLine
formatQuery() と同様ですが、返されるフォーマットされた文字列には改行が含まれません。
クエリが構文的に正しくない場合、例外をスローします。代わりに NULL を返すには、formatQuerySingleLineOrNull() 関数を利用してください。
構文
formatQuerySingleLine(query)
formatQuerySingleLineOrNull(query)
引数
query- フォーマット対象の SQL クエリ。String
返り値
- フォーマットされたクエリ。String。
例
SELECT formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3');
結果:
┌─formatQuerySingleLine('select a, b FRom tab WHERE a > 3 and b < 3')─┐
│ SELECT a, b FROM tab WHERE (a > 3) AND (b < 3) │
└─────────────────────────────────────────────────────────────────────────┘
variantElement
Variant カラムから指定された型のカラムを抽出します。
構文
variantElement(variant, type_name, [, default_value])
引数
variant— Variant カラム。Variant。type_name— 抽出する Variant 型の名前。String。default_value- 指定された型の Variant が存在しない場合に使用されるデフォルト値。任意の型を持つことができます。オプション。
返り値
- 指定された型を持つ
Variantカラムのサブカラム。
例
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;
┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [] │
│ 42 │ ᴺᵁᴸᴸ │ 42 │ [] │
│ Hello, World! │ Hello, World! │ ᴺᵁᴸᴸ │ [] │
│ [1,2,3] │ ᴺᵁᴸᴸ │ ᴺᵁᴸᴸ │ [1,2,3] │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘
variantType
Variant カラムの各行に対してその Variant 型名を返します。行が NULL を含む場合、その行に対して 'None' を返します。
構文
variantType(variant)
引数
variant— Variant カラム。Variant。
返り値
- 各行の Variant 型名を持つ Enum8 カラム。
例
CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;
┌─variantType(v)─┐
│ None │
│ UInt64 │
│ String │
│ Array(UInt64) │
└────────────────┘
SELECT toTypeName(variantType(v)) FROM test LIMIT 1;
┌─toTypeName(variantType(v))──────────────────────────────────────────┐
│ Enum8('None' = -1, 'Array(UInt64)' = 0, 'String' = 1, 'UInt64' = 2) │
└─────────────────────────────────────────────────────────────────────┘
minSampleSizeConversion
2つのサンプルにおける変換率（割合）を比較する A/B テストのための最小必要サンプルサイズを計算します。
構文
minSampleSizeConversion(baseline, mde, power, alpha)
こちらの記事で説明されている式を使用します。治療群と対照群が同じサイズであることを想定します。返される値は一つのグループに必要なサンプルサイズ（つまり、実験全体に必要なサンプルサイズは返される値の2倍）です。
引数
baseline— 基準変換率。Float。mde— 検出可能最低効果（MDE）はパーセンテージポイントで（例：基準変換率 0.25 の MDE が 0.03 の場合、0.25 ± 0.03 への変化が予想されます）。Float。power— テストの必要な統計力（1-タイプIIエラーの確率）。Float。alpha— テストの必要な有意水準（タイプIエラーの確率）。Float。
返り値
3つの要素を持つ名前つき Tuple：
"minimum_sample_size"— 必要なサンプルサイズ。Float64。"detect_range_lower"— 指定されたサンプルサイズでは検出できない範囲の下限（つまり、alphaとpowerが提供された場合、"detect_range_lower"以下のすべての値は検出可能です）。baseline - mdeとして計算されます。Float64。"detect_range_upper"— 指定されたサンプルサイズでは検出できない範囲の上限（つまり、alphaとpowerが提供された場合、"detect_range_upper"以上のすべての値は検出可能です）。baseline + mdeとして計算されます。Float64。
例
以下のクエリは、基準変換率が 25%、MDE が 3%、有意水準が 5%、望ましい統計力が 80% の A/B テストに対する必要なサンプルサイズを計算します：
SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size;
結果:
┌─sample_size───────────────────┐
│ (3396.077603219163,0.22,0.28) │
└───────────────────────────────┘
minSampleSizeContinuous
2つのサンプルにおける連続したメトリックの平均を比較する A/B テストのための最小必要サンプルサイズを計算します。
構文
minSampleSizeContinous(baseline, sigma, mde, power, alpha)
エイリアス: minSampleSizeContinous
こちらの記事で説明されている式を使用します。治療群と対照群が同じサイズであることを想定します。返される値は一つのグループに必要なサンプルサイズ（つまり、実験全体に必要なサンプルサイズは返される値の2倍）です。また、テストメトリックの治療群と対照群の標準偏差が同じであることを前提としています。
引数
baseline— メトリックの基準値。Integer または Float。sigma— メトリックの基準標準偏差。Integer または Float。mde— 基準値のパーセンテージとしての検出可能最低効果 (MDE) (例:基準値 112.25 の MDE は 0.03 これは、112.25 ± 112.25*0.03 への変化を意味します)。Integer または Float。power— テストの必要な統計力（1-タイプIIエラーの確率）。Integer または Float。alpha— テストの必要な有意水準（タイプIエラーの確率）。Integer または Float。
返り値
3つの要素を持つ名前つき Tuple：
"minimum_sample_size"— 必要なサンプルサイズ。Float64。"detect_range_lower"— 指定されたサンプルサイズでは検出できない範囲の下限（つまり、alphaとpowerが提供された場合、"detect_range_lower"以下のすべての値は検出可能です）。baseline * (1 - mde)として計算されます。Float64。"detect_range_upper"— 指定されたサンプルサイズでは検出できない範囲の上限（つまり、alphaとpowerが提供された場合、"detect_range_upper"以上のすべての値は検出可能です）。baseline * (1 + mde)として計算されます。Float64。
例
以下のクエリは、基準値 112.25、標準偏差 21.1、MDE 3%、有意水準 5%、望ましい統計力 80% のメトリックに対する A/B テストで必要なサンプルサイズを計算します：
SELECT minSampleSizeContinous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size;
結果:
┌─sample_size───────────────────────────┐
│ (616.2931945826209,108.8825,115.6175) │
└───────────────────────────────────────┘
connectionId
現在のクエリを送信したクライアントの接続 ID を UInt64 整数として取得し、返します。
構文
connectionId()
エイリアス: connection_id.
パラメータ
なし。
返り値
現在の接続 ID。UInt64。
実装の詳細
この関数は、デバッグシナリオや MySQL ハンドラ内での内部目的で役立ちます。MySQL の CONNECTION_ID 関数 と互換性があり、通常、プロダクションクエリでは使用されません。
例
クエリ:
SELECT connectionId();
0
getClientHTTPHeader
HTTP ヘッダーの値を取得します。
そのようなヘッダーが存在しないか、現在のリクエストが HTTP インターフェース経由で行われていない場合、この関数は空の文字列を返します。
特定の HTTP ヘッダー（例：Authentication および X-ClickHouse-*）は制限されています。
この関数を使用するには、設定 allow_get_client_http_header を有効にする必要があります。
セキュリティ上の理由から、この設定はデフォルトでは有効になっていません。一部のヘッダー、例えば Cookie は機密情報を含む可能性があるためです。
この関数における HTTP ヘッダーはケースセンシティブです。
関数が分散クエリのコンテキストで使用される場合、それはイニシエータノードでのみ非空結果を返します。
showCertificate
設定されている現在のサーバーの SSL 証明書に関する情報を表示します。OpenSSL 証明書を使用して接続を検証するよう ClickHouse を設定する方法については、SSL-TLS の設定を参照してください。
構文
showCertificate()
返り値
例
クエリ:
SELECT showCertificate() FORMAT LineAsString;
結果:
{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May 7 17:01:21 2024 GMT','not_after':'May 7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}
lowCardinalityIndices
LowCardinality カラムのDictionary内での値の位置を返します。位置は 1 から始まります。LowCardinality はパートごとにDictionaryを持っているため、この関数は異なるパートで同じ値に対して異なる位置を返すことがあります。
構文
lowCardinalityIndices(col)
引数
col— 低カーディナリティカラム。LowCardinality。
返り値
- 現在のパートのDictionary内での値の位置。UInt64。
例
クエリ:
DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;
-- 二つのパートを作成します:
INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');
SELECT s, lowCardinalityIndices(s) FROM test;
結果:
┌─s──┬─lowCardinalityIndices(s)─┐
1. │ ab │ 1 │
2. │ cd │ 2 │
3. │ ab │ 1 │
4. │ ab │ 1 │
5. │ df │ 3 │
└────┴──────────────────────────┘
┌─s──┬─lowCardinalityIndices(s)─┐
6. │ ef │ 1 │
7. │ cd │ 2 │
8. │ ab │ 3 │
9. │ cd │ 2 │
10. │ ef │ 1 │
└────┴──────────────────────────┘
lowCardinalityKeys
LowCardinality カラムのDictionaryの値を返します。ブロックがDictionaryのサイズより小さいまたは大きい場合、結果はデフォルト値で切り詰めまたは拡張されます。LowCardinalityはパートごとに異なるDictionaryを持っているため、この関数は異なるパートで異なるDictionaryの値を返すことがあります。
構文
lowCardinalityIndices(col)
引数
col— 低カーディナリティカラム。LowCardinality。
返り値
- Dictionaryのキー。UInt64。
例
クエリ:
DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;
-- 二つのパートを作成します:
INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');
SELECT s, lowCardinalityKeys(s) FROM test;
結果:
┌─s──┬─lowCardinalityKeys(s)─┐
1. │ ef │ │
2. │ cd │ ef │
3. │ ab │ cd │
4. │ cd │ ab │
5. │ ef │ │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
6. │ ab │ │
7. │ cd │ ab │
8. │ ab │ cd │
9. │ ab │ df │
10. │ df │ │
└────┴───────────────────────┘
displayName
config の display_name の値、または設定されていない場合はサーバーの完全修飾ドメイン名 (FQDN) を返します。
構文
displayName()
返される値
- 設定されている場合は config の
display_nameの値、または設定されていない場合はサーバーの FQDN。String。
例
display_name は config.xml で設定できます。例えば、display_name が 'production' に設定されているサーバーの場合：
<!-- clickhouse-client で表示される名前です。
デフォルトでは "production" を含むものはクエリプロンプトで赤でハイライトされます。
-->
<display_name>production</display_name>
クエリ:
SELECT displayName();
結果:
┌─displayName()─┐
│ production │
└───────────────┘
transactionID
トランザクション のIDを返します。
この関数はエクスペリメンタルな機能セットの一部です。設定にエクスペリメンタルなトランザクションサポートを有効にするための設定を追加します：
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
詳細については トランザクション (ACID) サポート のページを参照してください。
構文
transactionID()
返される値
start_csn、local_tidおよびhost_idから成るタプルを返します。Tuple。start_csn: このトランザクションが開始されたときに見られた最新のコミットタイムスタンプであるグローバルシーケンシャル番号。UInt64。local_tid: このホストが特定のstart_csn内で開始した各トランザクションにユニークであるローカルシーケンシャル番号。UInt64。host_id: このトランザクションを開始したホストの UUID。UUID。
例
クエリ:
BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;
結果:
┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘
transactionLatestSnapshot
読み取り可能なトランザクションの最新のスナップショット（コマンドシーケンシャル番号）を返します。
この関数はエクスペリメンタルな機能セットの一部です。設定にエクスペリメンタルなトランザクションサポートを有効にするための設定を追加します：
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</allow_experimental_transactions>
詳細については トランザクション (ACID) サポート のページを参照してください。
構文
transactionLatestSnapshot()
返される値
- トランザクションの最新スナップショット (CSN) を返します。UInt64
例
クエリ:
BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;
結果:
┌─transactionLatestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
transactionOldestSnapshot
ある実行中の トランザクション に対して表示可能な最古のスナップショット（コマンドシーケンス番号）を返します。
この関数はエクスペリメンタルな機能セットの一部です。設定にエクスペリメンタルなトランザクションサポートを有効にするための設定を追加します：
<clickhouse>
<allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>
詳細については トランザクション (ACID) サポート のページを参照してください。
構文
transactionOldestSnapshot()
返される値
- トランザクションの最古のスナップショット (CSN) を返します。UInt64
例
クエリ:
BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;
結果:
┌─transactionOldestSnapshot()─┐
│ 32 │
└─────────────────────────────┘
getSubcolumn
テーブルの式または識別子とサブカラムの名前を持つ定数文字列を取り、式から抽出されたリクエストされたサブカラムを返します。
構文
getSubcolumn(col_name, subcol_name)
引数
col_name— テーブルの式または識別子。Expression、Identifier。subcol_name— サブカラムの名前。String。
返される値
- 抽出されたサブカラムを返します。
例
クエリ:
CREATE TABLE t_arr (arr Array(Tuple(subcolumn1 UInt32, subcolumn2 String))) ENGINE = MergeTree ORDER BY tuple();
INSERT INTO t_arr VALUES ([(1, 'Hello'), (2, 'World')]), ([(3, 'This'), (4, 'is'), (5, 'subcolumn')]);
SELECT getSubcolumn(arr, 'subcolumn1'), getSubcolumn(arr, 'subcolumn2') FROM t_arr;
結果:
┌─getSubcolumn(arr, 'subcolumn1')─┬─getSubcolumn(arr, 'subcolumn2')─┐
1. │ [1,2] │ ['Hello','World'] │
2. │ [3,4,5] │ ['This','is','subcolumn'] │
└─────────────────────────────────┴─────────────────────────────────┘
getTypeSerializationStreams
データ型のストリームパスを列挙します。
この関数は開発者向けに意図されています。
構文
getTypeSerializationStreams(col)
引数
col— データタイプが検出されるカラムまたはデータタイプの文字列表現。
返される値
例
クエリ:
SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2));
結果:
┌─getTypeSerializationStreams(('a', 1, 'b', 2))─────────────────────────────────────────────────────────────────────────┐
1. │ ['{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), Regular}','{TupleElement(4), Regular}'] │
└───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
クエリ:
SELECT getTypeSerializationStreams('Map(String, Int64)');
結果:
┌─getTypeSerializationStreams('Map(String, Int64)')────────────────────────────────────────────────────────────────┐
1. │ ['{ArraySizes}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}'] │
└──────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
globalVariable
定数文字列引数を取り、その名前のグローバル変数の値を返します。この関数はMySQLとの互換性のために意図されており、ClickHouseの通常の操作には必要ではありません。定義されているのは少数のダミーのグローバル変数のみです。
構文
globalVariable(name)
引数
name— グローバル変数名。String。
返される値
- 変数
nameの値を返します。
例
クエリ:
SELECT globalVariable('max_allowed_packet');
結果:
┌─globalVariable('max_allowed_packet')─┐
│ 67108864 │
└──────────────────────────────────────┘