その他の関数

「その他の関数」カテゴリのドキュメント

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

​

FQDN

導入バージョン: v20.1.0

ClickHouseサーバーの完全修飾ドメイン名を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返す場合があります。

構文

FQDN()

別名: fullHostName

引数

• なし。

戻り値

ClickHouseサーバーの完全修飾ドメイン名を返します。String

例

使用例

Query

SELECT fqdn()

Response

┌─FQDN()────────────────────────┐
│ clickhouse.us-east-2.internal │
└───────────────────────────────┘

​

MACNumToString

導入バージョン: v1.1.0

UInt64 型の数値を、ビッグエンディアン形式の MAC アドレスとして解釈します。 対応する MAC アドレスを、AA:BB:CC:DD:EE:FF フォーマット (コロン区切りの16進数表記) の文字列として返します。

構文

MACNumToString(num)

引数

• num — UInt64 型の数値。UInt64

戻り値

AA:BB:CC:DD:EE:FF 形式の MAC アドレスを返します。String

例

使用例

Query

SELECT MACNumToString(149809441867716) AS mac_address;

Response

┌─mac_address───────┐
│ 88:40:3A:91:07:C4 │
└───────────────────┘

​

MACStringToNum

導入バージョン: v1.1.0

MACNumToString の逆関数です。MAC アドレスの形式が不正な場合は、0 を返します。

構文

MACStringToNum(s)

引数

• s — MACアドレスの文字列。String

戻り値

UInt64 型の数値を返します。UInt64

例

使用例

Query

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

Response

1108152157446

​

MACStringToOUI

導入バージョン: v1.1.0

AA:BB:CC:DD:EE:FF 形式の MAC アドレス (コロン区切りの16進数表記) を受け取り、先頭 3 オクテットを UInt64 値として返します。MAC アドレスの形式が無効な場合は 0 を返します。

構文

MACStringToOUI(s)

引数

• s — MAC アドレスの文字列。String

戻り値

先頭の 3 オクテットを UInt64 の数値として返します。UInt64

例

使用例

Query

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

Response

20566

​

authenticatedUser

導入バージョン: v25.11.0

セッションユーザーが EXECUTE AS コマンドで切り替えられている場合、この関数は、認証とセッションの作成に使われた元のユーザー名を返します。 別名: authUser()

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

authenticatedUser()

別名: authUser

引数

• なし。

戻り値

認証されたユーザー名。String

例

使用例

Query

CREATE USER u1;
EXECUTE AS u1 SELECT currentUser(), authenticatedUser();
DROP USER u1;

Response

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

​

bar

導入バージョン: v1.1.0

棒グラフを生成します。 x = max の場合は width 文字幅となる、(x - min) に比例した幅の帯を描画します。 帯は 1 文字の 8 分の 1 の精度で描画されます。

構文

bar(x, min, max[, width])

引数

• x — 表示するサイズ。(U)Int* または Float* または Decimal
• min — 最小値。(U)Int* または Float* または Decimal
• max — 最大値。(U)Int* または Float* または Decimal
• width — オプション。バーの幅 (文字数) です。既定値は 80 です。const (U)Int* または const Float* または const Decimal

戻り値

Unicodeアートのバーを表す文字列を返します。String

例

使用例

Query

CREATE TABLE hits (EventTime DateTime('UTC')) ENGINE = Memory;

-- One row per page view, spread over the hours of a day.
INSERT INTO hits
SELECT toDateTime('2026-01-01 00:00:00', 'UTC') + toIntervalHour(hour)
FROM (
    SELECT
        number AS hour,
        [293, 181, 115, 85, 69, 78, 113, 171, 278, 391, 458, 494, 510, 523, 540, 528, 539, 524, 506, 521, 522, 542, 494, 400][number + 1] AS count
    FROM numbers(24)
)
ARRAY JOIN range(count);

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600, 20) AS bar
FROM hits
GROUP BY h
ORDER BY h ASC

Response

┌──h─┬───c─┬─bar────────────────┐
│  0 │ 293 │ █████████▊         │
│  1 │ 181 │ ██████             │
│  2 │ 115 │ ███▊               │
│  3 │  85 │ ██▊                │
│  4 │  69 │ ██▎                │
│  5 │  78 │ ██▌                │
│  6 │ 113 │ ███▊               │
│  7 │ 171 │ █████▋             │
│  8 │ 278 │ █████████▎         │
│  9 │ 391 │ █████████████      │
│ 10 │ 458 │ ███████████████▎   │
│ 11 │ 494 │ ████████████████▍  │
│ 12 │ 510 │ █████████████████  │
│ 13 │ 523 │ █████████████████▍ │
│ 14 │ 540 │ ██████████████████ │
│ 15 │ 528 │ █████████████████▌ │
│ 16 │ 539 │ █████████████████▉ │
│ 17 │ 524 │ █████████████████▍ │
│ 18 │ 506 │ ████████████████▊  │
│ 19 │ 521 │ █████████████████▎ │
│ 20 │ 522 │ █████████████████▍ │
│ 21 │ 542 │ ██████████████████ │
│ 22 │ 494 │ ████████████████▍  │
│ 23 │ 400 │ █████████████▎     │
└────┴─────┴────────────────────┘

​

blockNumber

導入バージョン: v1.1.0

その行を含むブロックの単調増加するシーケンス番号を返します。 返される ブロック 番号はベストエフォートで更新されるため、完全に正確でない場合があります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

blockNumber()

引数

• なし。

戻り値

その行が含まれるデータブロックのシーケンス番号。UInt64

例

基本的な使い方

Query

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

Response

┌─blockNumber()─┐
│             6 │
│             6 │
│             7 │
│             7 │
│             8 │
│             8 │
│             9 │
│             9 │
│            10 │
│            10 │
└───────────────┘

​

blockSerializedSize

導入バージョン: v20.3.0

ディスク上にある値ブロックの非圧縮サイズを、バイト単位で返します。

この関数は非決定論的です。同じ引数に対しても、異なる結果を返すことがあります。

構文

blockSerializedSize(x1[, x2[, ...]])

引数

• x1[, x2, ...] — ブロックの非圧縮サイズを取得する対象となる、任意の数の値。Any

戻り値

圧縮されていない値のブロックについて、ディスクに書き込まれるバイト数を返します。UInt64

例

使用例

Query

SELECT blockSerializedSize(maxState(1)) AS x;

Response

┌─x─┐
│ 2 │
└───┘

​

blockSize

導入バージョン: v1.1.0

ClickHouse では、クエリは ブロック (chunk) 単位で処理されます。 この関数は、呼び出し対象のブロックのサイズ (行数) を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

blockSize()

引数

• なし。

戻り値

現在のブロック内の行数を返します。UInt64

例

使用例

Query

SELECT blockSize()
FROM system.numbers LIMIT 5

Response

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

​

buildId

導入バージョン: v20.5.0

実行中の ClickHouseサーバー バイナリについて、コンパイラが生成したビルド ID を返します。 分散テーブルのコンテキストで実行した場合、この関数は各分片に対応する値を持つ通常のカラムを返します。 それ以外の場合は、定数値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

buildId()

引数

• なし

戻り値

ビルドIDを返します。 String

例

使用例

Query

SELECT buildId()

Response

┌─buildId()────────────────────────────────┐
│ B49BA4BC500E5E850F832BEC918885516B22FC0E │
└──────────────────────────────────────────┘

​

byteSize

導入バージョン: v21.1.0

メモリ内における引数の非圧縮バイトサイズの推定値を返します。 String 型の引数の場合、この関数は文字列の長さ + 8 (長さ) を返します。 この関数に複数の引数がある場合、それらのバイトサイズの合計を返します。

構文

byteSize(arg1[, arg2, ...])

引数

• arg1[, arg2, ...] — 非圧縮時のバイトサイズを推定する対象となる、任意のデータ型の値。Any

戻り値

メモリ内における引数のバイトサイズの推定値を返します。UInt64

例

使用例

Query

SELECT byteSize('string')

Response

┌─byteSize('string')─┐
│                 14 │
└────────────────────┘

複数の引数

Query

SELECT byteSize(NULL, 1, 0.3, '')

Response

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         18 │
└────────────────────────────┘

​

colorOKLABToSRGB

導入バージョン: v26.2.0

色を OKLab 知覚色空間から sRGB 色空間に変換します。

入力色は OKLab 色空間で指定します。入力値が 一般的な OKLab の範囲外にある場合、結果は実装依存になります。

OKLab は 3 つの部分を使用します。

• L: 知覚的な明度 (通常は [0..1] の範囲)
• a: 緑-赤の対立軸
• b: 青-黄の対立軸

a および b の部分は理論上は無制限ですが、実際には -0.4 から 0.4 の範囲に収まります。 OKLab は、コンピュートコストを低く抑えつつ、 知覚的に均一になるよう設計されています。

この変換は colorSRGBToOKLAB の逆変換となることを意図しており、 次の段階で構成されます。

1. OKLab から Linear sRGB への変換。
2. Linear sRGB からガンマエンコードされた sRGB への変換。

オプションのガンマ 引数は、Linear sRGB からガンマエンコードされた RGB 値への変換時に使用する指数を指定します。指定しない場合は、 colorSRGBToOKLAB との一貫性を保つため、既定のガンマ 値が使用されます。

OKLab 色空間とその sRGB との関係の詳細については、https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab を参照してください。

構文

colorOKLABToSRGB(tuple [, gamma])

引数

• tuple — 3 つの数値 L、a、b からなるタプルです。L の範囲は [0...1] です。Tuple(Float64, Float64, Float64)
• gamma — 省略可能です。各チャネル x に (x ^ (1 / gamma)) * 255 を適用して、Linear sRGB を sRGB に戻す際に使用する指数です。既定値は 2.2 です。Float64

戻り値

sRGB の色値を表すタプル (R, G, B) を返します。Tuple(Float64, Float64, Float64)

例

OKLAB を sRGB (Float) に変換

Query

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

Response

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

OKLABをsRGB (UInt8) に変換

Query

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

Response

┌─RGB───────┐
│ (255,0,0) │
└───────────┘

​

colorOKLCHToSRGB

導入バージョン: v25.7.0

色を OKLCH 知覚色空間から、一般的な sRGB 色空間に変換します。

L が範囲 [0...1] 外にある場合、C が負の場合、または H が範囲 [0...360] 外にある場合、結果は実装依存です。

OKLCH は、OKLab 色空間の円筒座標表現です。 3 つの座標は、L (範囲 [0...1] の明度) 、C (彩度 >= 0) 、H ([0...360] の範囲の度数による色相) です。 OKLab/OKLCH は、知覚的に均一でありながら、計算コストを低く抑えられるよう設計されています。

この変換は colorSRGBToOKLCH の逆変換です。

1. OKLCH から OKLab へ。
2. OKLab から Linear sRGB へ
3. Linear sRGB から sRGB へ

2 番目の引数 gamma は最後の段階で使用されます。

OKLCH 空間における色の例と、それらが sRGB の色にどのように対応するかについては、https://oklch.com/ を参照してください。

構文

colorOKLCHToSRGB(tuple [, gamma])

引数

• tuple — 3 つの数値 L、C、H から成るタプル。L は範囲 [0...1]、C >= 0、H は範囲 [0...360] です。Tuple(Float64, Float64, Float64)
• gamma — 任意。各チャネル x に (x ^ (1 / gamma)) * 255 を適用して、線形 sRGB を sRGB に変換する際に使用する指数です。デフォルトは 2.2 です。Float64

戻り値

sRGB の色値を表すタプル (R, G, B) を返します。Tuple(Float64, Float64, Float64)

例

OKLCH を sRGB に変換する

Query

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

Response

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

OKLCH を sRGB (UInt8) に変換

Query

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

Response

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

​

colorSRGBToOKLAB

導入バージョン: v26.2.0

sRGB 色空間でエンコードされた色を、知覚的に均一な OKLAB 色空間に変換します。

いずれかの入力チャネルが [0...255] の範囲外にある場合、またはガンマ値が 0 以下の場合の動作は実装依存です。

OKLAB は知覚的に均一な色空間です。 その 3 つの座標は、L ([0...1] の範囲の明度) 、a（緑-赤軸）、b（青-黄軸） です。 OKLab は、計算コストを抑えつつ知覚的に均一になるよう設計されています。

変換は次の 2 段階で行われます。

1. sRGB から Linear sRGB
2. Linear sRGB から OKLab

構文

colorSRGBToOKLAB(tuple[, gamma])

引数

• tuple — 範囲 [0...255] の 3 つの値 R、G、B からなるタプル。Tuple(UInt8, UInt8, UInt8)
• gamma — オプション。各チャネル x に (x / 255)^gamma を適用して sRGB を線形化するために使用する指数です。デフォルトは 2.2 です。Float64

戻り値

OKLAB 色空間の値を表すタプル (L, a, b) を返します。Tuple(Float64, Float64, Float64)

例

sRGB を OKLAB に変換する

Query

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

Response

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

​

colorSRGBToOKLCH

導入バージョン: v25.7.0

sRGB 色空間でエンコードされた色を、知覚的に均一な OKLCH 色空間に変換します。

いずれかの入力チャネルが [0...255] の範囲外であるか、ガンマ値が 0 以下の場合の動作は実装依存です。

OKLCH は、OKLab 色空間の円筒座標表現です。 その 3 つの座標は、L ([0...1] の範囲の明度) 、C (>= 0 の彩度) 、H ([0...360] の範囲の度数で表した色相) です。 OKLab/OKLCH は、計算コストを抑えつつ知覚的に均一になるよう設計されています。

変換は次の 3 段階で行われます。

1. sRGB から Linear sRGB
2. Linear sRGB から OKLab
3. OKLab から OKLCH。

OKLCH 空間における色の参考例と、それらが sRGB の色にどう対応するかについては、https://OKLCH.com/ を参照してください。

構文

colorSRGBToOKLCH(tuple[, gamma])

引数

• tuple — 範囲 [0...255] の 3 つの値 R、G、B からなるタプル。Tuple(UInt8, UInt8, UInt8)
• gamma — 省略可。各チャネル x に (x / 255)^gamma を適用して sRGB を線形化する際に使う指数。既定値は 2.2 です。Float64

戻り値

OKLCH 色空間の値を表すタプル (L, C, H) を返します。Tuple(Float64, Float64, Float64)

例

sRGB を OKLCH に変換

Query

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

Response

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

​

connectionId

導入バージョン: v21.3.0

現在のクエリを送信したクライアントの接続 ID を返します。 この関数は、デバッグ時に特に有用です。 これは、MySQL の CONNECTION_ID 関数との互換性を保つために作成されました。 通常、本番環境のクエリでは使用されません。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

connectionId()

引数

• ありません。

戻り値

現在のクライアントの接続 ID を返します。UInt64

例

使用例

Query

SELECT connectionId();

Response

┌─connectionId()─┐
│              0 │
└────────────────┘

​

countDigits

導入バージョン: v20.8.0

値の表現に必要な10進数の桁数を返します。

この関数は10進数値の scale を考慮します。つまり、基になる整数型 (value * scale) に対して結果を計算します。

例:

• countDigits(42) = 2
• countDigits(42.000) = 5
• countDigits(0.04200) = 4

Decimal64 の overflow は countDigits(x) > 18 で確認できますが、 isDecimalOverflow を使用するより低速です。

構文

countDigits(x)

引数

• x — 整数または小数値。(U)Int* または Decimal

戻り値

x の表現に必要な桁数を返します。UInt8

例

使用例

Query

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));

Response

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

​

currentDatabase

導入バージョン: v1.1.0

現在のデータベース名を返します。 データベースを指定する必要がある CREATE TABLE クエリのテーブルエンジンパラメータで便利です。

SETステートメント も参照してください。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

currentDatabase()

別名: current_database, DATABASE, SCHEMA

引数

• ありません。

戻り値

現在のデータベース名を返します。 String

例

使用例

Query

SELECT currentDatabase()

Response

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

SQL 標準構文

Query

SELECT CURRENT_DATABASE

Response

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

​

currentHandler

導入バージョン: v26.6.0

クエリを呼び出した、SQL で定義された HTTP ハンドラー (CREATE HANDLER で作成) の名前を返します。 このようなハンドラー経由でクエリが呼び出されなかった場合は、空文字列を返します。

呼び出されたハンドラーに応じてクエリの動作をカスタマイズする場合に役立ちます。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

currentHandler()

引数

• なし。

戻り値

現在のハンドラー名を返します。String

例

使用例

Query

SELECT currentHandler()

​

currentProfiles

導入バージョン: v21.9.0

現在のユーザーに設定されている設定プロファイルの Array を返します。

この関数は非決定論的です。同じ引数に対しても、異なる結果を返すことがあります。

構文

currentProfiles()

引数

• ありません。

戻り値

現在のユーザーの設定プロファイルの Array を返します。Array(String)

例

使用例

Query

SELECT currentProfiles();

Response

┌─currentProfiles()─┐
│ ['default']       │
└───────────────────┘

​

currentQueryID

導入バージョン: v25.2.0

現在の Query id を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

currentQueryID()

別名: current_query_id

引数

• なし。

戻り値

例

例

Query

SELECT currentQueryID();

Response

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

​

currentRequestURL

導入バージョン: v26.6.0

クエリを実行した HTTP リクエストの URL (パスおよびクエリ文字列) を返します。 クエリが HTTP 経由で実行されなかった場合は、空文字列を返します。

SQL で定義された HTTP ハンドラー (CREATE HANDLER) と組み合わせることで、リクエストパスに 埋め込まれたパラメータを抽出できます。

この関数は非決定論的です。同じ引数に対して異なる結果を返す場合があります。

構文

currentRequestURL()

引数

• なし。

戻り値

現在のHTTPリクエストのURLを返します。String

例

使用例

Query

SELECT currentRequestURL()

​

currentRoles

導入バージョン: v21.9.0

現在のユーザーに付与されているロールの Array を返します。

この関数は非決定論的です。同じ引数に対して、異なる結果を返すことがあります。

構文

currentRoles()

引数

• なし。

戻り値

現在のユーザーに割り当てられているロールの Array を返します。Array(String)

例

使用例

Query

SELECT currentRoles();

Response

┌─currentRoles()─┐
│ []             │
└────────────────┘

​

currentSchemas

導入バージョン: v23.7.0

関数 currentDatabase と同じですが、次の点が異なります。

• 無視される真偽値の引数を受け取ります
• データベース名を、単一の値を含む Array として返します。

関数 currentSchemas は、PostgreSQL との互換性のためにのみ存在します。 代わりに currentDatabase を使用してください。

SET ステートメント も参照してください。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

currentSchemas(bool)

別名: current_schemas

引数

• bool — 無視されるブール値。Bool

戻り値

現在のデータベース名を含む単一要素の Array を返します。Array(String)

例

使用例

Query

SELECT currentSchemas(true)

Response

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

​

currentUser

導入バージョン: v20.1.0

現在のユーザー名を返します。 分散クエリの場合は、クエリを開始したユーザー名が返されます。

この関数は非決定論的です。同じ引数に対して、異なる結果を返すことがあります。

構文

currentUser()

別名: session_user, current_user, user

引数

• なし。

戻り値

現在のユーザー名、またはクエリを開始したユーザーのログイン名を返します。String

例

使用例

Query

SELECT currentUser()

Response

┌─currentUser()─┐
│ default       │
└───────────────┘

SQL 標準構文

Query

SELECT CURRENT_USER

Response

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

​

defaultProfiles

導入バージョン: v21.9.0

現在のユーザーに対するデフォルトの設定プロファイル名の Array を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

defaultProfiles()

引数

• なし

戻り値

現在のユーザーのデフォルトの設定プロファイル名の Array を返します。Array(String)

例

使用例

Query

SELECT defaultProfiles();

Response

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

​

defaultRoles

導入バージョン: v21.9.0

現在のユーザーに設定されているデフォルトロールの Array を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

defaultRoles()

引数

• なし。

戻り値

現在のユーザーのデフォルトロールの Array を返します。 Array(String)

例

使用例

Query

SELECT defaultRoles();

Response

┌─defaultRoles()─┐
│ []             │
└────────────────┘

​

defaultValueOfArgumentType

導入バージョン: v1.1.0

指定されたデータ型のデフォルト値を返します。 ユーザーが設定したカスタムカラムのデフォルト値は含まれません。

構文

defaultValueOfArgumentType(expression)

引数

• expression — 任意の型の値、または任意の型の値になる式。Any

戻り値

数値型の場合は 0、文字列型の場合は空文字列、Nullable 型の場合は NULL を返します。UInt8 または String または NULL

例

使用例

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

Response

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

Nullable の例

Query

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

Response

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

​

defaultValueOfTypeName

導入バージョン: v1.1.0

指定された型名のデフォルト値を返します。

構文

defaultValueOfTypeName(type)

引数

• type — 型名を表す文字列。 String

戻り値

指定した型名のデフォルト値を返します。数値型の場合は 0、文字列型の場合は空文字列、Nullable UInt8 または String、あるいは NULL の場合は NULL です。

例

使用例

Query

SELECT defaultValueOfTypeName('Int8');

Response

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

Nullableの例

Query

SELECT defaultValueOfTypeName('Nullable(Int8)');

Response

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

​

digits

導入バージョン: v26.7.0

指定した位置 offset から始まる数値 n の桁を返します。 数え始めは 1 で、ルールは次のとおりです。

• offset が 0 の場合、offset は 1-based であるため、例外がスローされます。
• offset が負の値の場合、数値の先頭ではなく末尾から offset 桁分の位置を起点に数えます。
• offset が n の桁数より大きい場合は、0 が返されます。

省略可能な引数 length には、次のルールが適用されます。

• length が正の値の場合、offset から取得する桁数を意味します
• length が負の値の場合、数値の右側から除外する桁数を意味します

文字列に対して同様の操作を行う substring 関数も参照してください。

構文

digits(n, offset[, length])

引数

• n — 桁を取り出す元となる数値。(U)Int8 または (U)Int16 または (U)Int32 または (U)Int64
• offset — n 内での桁の開始位置。(U)Int8 または (U)Int16 または (U)Int32 または (U)Int64
• length — 任意。桁数の最大長。(U)Int8 または (U)Int16 または (U)Int32 または (U)Int64

戻り値

選択した n の桁を UInt64 として解釈した値。選択範囲が空の場合は 0 を返します。先頭のゼロは保持されません。UInt64

例

正のオフセット

Query

SELECT digits(1234567890, 7)

Response

7890

正のオフセットと長さ

Query

SELECT digits(1234567890, 7, 2)

Response

78

負のオフセットは右から数えます

Query

SELECT digits(1234567890, -3)

Response

890

長さが負の場合、右側の数字は除外されます

Query

SELECT digits(1234567890, 3, -2)

Response

345678

末尾を超える位置のオフセットでは 0 が返されます

Query

SELECT digits(1234567890, 11)

Response

0

​

displayName

導入バージョン: v22.11.0

config の display_name の値を返します。設定されていない場合は、サーバーの完全修飾ドメイン名 (FQDN) を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

displayName()

引数

• なし。

戻り値

config の display_name の値を返します。設定されていない場合は、サーバーの FQDN を返します。String

例

使用例

Query

SELECT displayName();

Response

┌─displayName()─┐
│ production    │
└───────────────┘

​

dumpColumnStructure

導入バージョン: v1.1.0

カラムの内部構造とそのデータ型について、詳細な説明を出力します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

dumpColumnStructure(x)

引数

• x — 説明を取得する対象の値。Any

戻り値

値の表現に使用されるカラム構造の説明を返します。String

例

使用例

Query

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

Response

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

​

enabledProfiles

導入バージョン: v21.9.0

現在のユーザーで有効な設定プロファイル名の Array を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

enabledProfiles()

引数

• なし。

戻り値

現在のユーザーで有効になっている設定プロファイル名の Array を返します。 Array(String)

例

使用例

Query

SELECT enabledProfiles();

Response

┌─enabledProfiles()─┐
│ ['default']       │
└───────────────────┘

​

enabledRoles

導入バージョン: v21.9.0

現在のユーザーで有効になっているロールの Array を返します。

この関数は非決定論的であり、同じ引数に対して異なる結果を返すことがあります。

構文

enabledRoles()

引数

• なし。

戻り値

現在のユーザーで有効なロール名の Array を返します。Array(String)

例

使用例

Query

SELECT enabledRoles();

Response

┌─enabledRoles()─┐
│ []             │
└────────────────┘

​

errorCodeToName

導入バージョン: v20.12.0

数値の ClickHouse エラーコードに対応するエラー名のテキストを返します。 数値のエラーコードとエラー名の対応はこちらで確認できます。

構文

errorCodeToName(error_code)

引数

• error_code — ClickHouse のエラーコード。(U)Int* または Float* または Decimal

戻り値

error_code のテキスト形式の名前を返します。String

例

使用例

Query

SELECT errorCodeToName(252);

Response

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

​

file

導入バージョン: v21.3.0

ファイルを文字列として読み取り、その内容を指定したカラムに読み込みます。 ファイルの内容は解釈されません。

file テーブル関数も参照してください。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

file(path[, default])

引数

• path — user_files_path からの相対パス。ワイルドカード *、**、?、{abc,def}、{N..M} をサポートします。ここで、N と M は数値、'abc' と 'def' は文字列です。String
• default — ファイルが存在しない場合、またはアクセスできない場合に返される値。String または NULL

戻り値

ファイルの内容を文字列として返します。String

例

ファイルをテーブルに挿入

Query

INSERT INTO FUNCTION file('a.txt', 'RawBLOB') SELECT 'Hello' SETTINGS engine_file_truncate_on_insert = 1;
INSERT INTO FUNCTION file('b.txt', 'RawBLOB') SELECT 'World!' SETTINGS engine_file_truncate_on_insert = 1;

CREATE TABLE data (a String, b String) ENGINE = Memory;
INSERT INTO data SELECT file('a.txt'), file('b.txt');

SELECT * FROM data;

Response

┌─a─────┬─b──────┐
│ Hello │ World! │
└───────┴────────┘

​

filesystemAvailable

導入バージョン: v20.1.0

データベースの永続化先があるファイルシステムの空き容量を返します。 オペレーティングシステム用に一部の領域が予約されているため、戻り値は常に合計の空き容量 (filesystemUnreserved) よりも小さくなります。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

filesystemAvailable([disk_name])

引数

• disk_name — 任意。空き容量を取得する対象のディスク名です。省略した場合は、デフォルトのディスクが使用されます。 String または FixedString

戻り値

利用可能な残りの空き容量をバイト単位で返します。 UInt64

例

使用例

Query

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

Response

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

​

filesystemCapacity

導入バージョン: v20.1.0

ファイルシステムの容量をバイト単位で返します。 データディレクトリへの path を設定しておく必要があります。

この関数は非決定論的です。同じ引数でも異なる結果を返す場合があります。

構文

filesystemCapacity([disk_name])

引数

• disk_name — 任意。容量を取得する対象のディスク名です。省略した場合は、デフォルトのディスクが使用されます。String または FixedString

戻り値

ファイルシステムの容量をバイト単位で返します。UInt64

例

使用例

Query

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

Response

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

​

filesystemUnreserved

導入バージョン: v22.12.0

データベースの永続化ストレージをホストするファイルシステム上の空き容量の総量を返します (以前の名前は filesystemFree) 。 関連項目: filesystemAvailable。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

filesystemUnreserved([disk_name])

引数

• disk_name — 省略可能。空き容量の合計を取得する対象のディスク名です。省略した場合は、デフォルトのディスクが使用されます。String または FixedString

戻り値

空き容量をバイト単位で返します。UInt64

例

使用例

Query

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

Response

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

​

finalizeAggregation

導入バージョン: v1.1.0

集約状態を受け取り、この関数は集約結果を返します (-State コンビネータを使用している場合は、確定された状態を返します) 。

構文

finalizeAggregation(state)

引数

• state — 集約状態。AggregateFunction

戻り値

集約を確定した結果を返します。Any

例

使用例

Query

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

Response

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

initializeAggregation と併用

Query

SET allow_deprecated_error_prone_window_functions = 1;
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(5);

Response

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

​

flipCoordinates

導入バージョン: v25.11.0

ジオメトリオブジェクトの x 座標と y 座標を入れ替えます。この操作では緯度と経度が入れ替わるため、異なる座標系間の変換や座標順序の修正に役立ちます。

Point では x 座標と y 座標を入れ替えます。複雑なジオメトリ (MultiPoint、LineString、Polygon、MultiPolygon、Ring、MultiLineString) では、各座標ペアにこの変換が再帰的に適用されます。

この関数は、個別のジオメトリ型 (Point、MultiPoint、Ring、Polygon、MultiPolygon、LineString、MultiLineString) と Geometry Variant 型の両方をサポートします。

構文

flipCoordinates(geometry)

引数

• geometry — 変換対象のジオメトリ。対応する型: Point (Tuple(Float64, Float64)), MultiPoint (Array(Point)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)), または Geometry (これらのいずれかの型を含むバリアント)。

戻り値

座標が反転されたジオメトリ。戻り値の型は入力型と一致します。Point または MultiPoint または Ring または Polygon または MultiPolygon または LineString または MultiLineString または Geometry

例

basic_point

Query

SELECT flipCoordinates((1.0, 2.0));

Response

(2,1)

リング

Query

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

Response

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

polygon

Query

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

Response

[[(2,1),(4,3)],[(6,5),(8,7)]]

geometry_wkt

Query

SELECT flipCoordinates(readWkt('POINT(10 20)'));

Response

(20,10)

geometry_polygon_wkt

Query

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

Response

[[(0,0),(0,5),(5,5),(5,0),(0,0)]]

​

formatQuery

導入バージョン: v23.10.0

指定された SQL クエリを整形して返します。出力は複数行になる場合があります。パースエラーが発生した場合は例外をスローします。 [example:multiline]

構文

formatQuery(query)

引数

• query — フォーマットする SQL クエリ。 String

戻り値

フォーマットされたクエリ String

例

複数行

Query

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

​

formatQueryFromJSON

導入バージョン: v26.8.0

SQL AST (parseQueryToJSON によって生成される) のJSON表現を受け取り、SQLクエリ文字列として再フォーマットします。

引数が1つの場合は、正規化された形式のSQLを生成します。 引数が2つの場合 (json, original_query) は、元のクエリのコメント、空白、インデントを可能な限り保持します。

デシリアライズされたASTは、現在のセッションの max_ast_depth および max_ast_elements 設定による制限を受けます。 この関数を parseQueryToJSON と組み合わせることで、JSON AST形式を介してクエリを プログラムから検査および変換できます。

構文

formatQueryFromJSON(json[, original_query])

引数

• json — SQL AST を表す JSON 文字列。String
• original_query — 任意。フォーマットを保持するための元の SQL クエリ。String

戻り値

SQL クエリ文字列。String

例

往復変換

Query

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'));

Response

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'))─┐
│ SELECT a, b FROM t WHERE x > 1                                          │
└─────────────────────────────────────────────────────────────────────────┘

フォーマットを保持

Query

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t');

Response

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t')─┐
│ SELECT /* comment */ a FROM t                                                             │
└───────────────────────────────────────────────────────────────────────────────────────────┘

​

formatQueryOrNull

導入バージョン: v23.11.0

指定されたSQLクエリを整形したものを返します。結果は複数行になる場合があります。パースエラーの場合はNULLを返します。 [example:multiline]

構文

formatQueryOrNull(query)

引数

• query — 整形する対象のSQLクエリ。String

戻り値

フォーマットされたクエリ String

例

複数行

Query

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

​

formatQuerySingleLine

導入バージョン: v23.10.0

formatQuery() と同様ですが、返される整形済み文字列には改行が含まれません。パースエラーが発生した場合は例外をスローします。 [example:multiline]

構文

formatQuerySingleLine(query)

引数

• query — フォーマット対象のSQLクエリ。String

戻り値

フォーマット後のクエリ String

例

複数行

Query

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

​

formatQuerySingleLineOrNull

導入バージョン: v23.11.0

formatQuery() と同様ですが、返されるフォーマット済み文字列には改行が含まれません。パース エラーが発生した場合は NULL を返します。 [example:multiline]

構文

formatQuerySingleLineOrNull(query)

引数

• query — フォーマット対象のSQLクエリ。String

戻り値

フォーマット済みのクエリ String

例

複数行

Query

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

Response

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

​

formatReadableDecimalSize

導入バージョン: v22.11.0

サイズ (バイト数) を受け取り、接尾辞 (KB、MB など) 付きの、読みやすく丸められたサイズを文字列として返します。

この関数の逆の操作は parseReadableSize です。

構文

formatReadableDecimalSize(value[, precision])

引数

• value — バイト単位のサイズ。Int8 または Int16 または Int32 または Int64 または UInt8 または UInt16 または UInt32 または UInt64 または Float32 または Float64 または Decimal
• precision — 任意。精度。デフォルトは 2 です。const UInt8

戻り値

接尾辞付きの、読みやすく丸められたサイズを文字列で返します。String

例

ファイルサイズを見やすい形式で表示する

Query

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

Response

┌─filesize_bytes─┬─filesize──┐
│              1 │ 1.00 B    │
│           1024 │ 1.02 KB   │
│        1048576 │ 1.05 MB   │
│      192851925 │ 192.85 MB │
└────────────────┴───────────┘

精度を明示的に指定する

Query

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

​

formatReadableQuantity

導入バージョン: v20.10.0

数値を指定すると、この関数は接尾辞 (thousand、million、billion など) を付けた丸め後の数値を文字列として返します。

この関数は入力として任意の数値型を受け付けますが、内部的にはそれらを Float64 にキャストします。 値が大きい場合、結果が不正確になることがあります。

構文

formatReadableQuantity(value[, precision])

引数

• value — フォーマットする数値です。Int8 または Int16 または Int32 または Int64 または UInt8 または UInt16 または UInt32 または UInt64 または Float32 または Float64 または Decimal
• precision — 任意です。精度を指定します。デフォルトは 2 です。const UInt8

戻り値

接尾辞付きに丸めた数値を文字列として返します。String

例

数値を接尾辞付きでフォーマットする

Query

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

Response

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

精度を明示的に指定する

Query

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals────┐
│ 99 trillion │ 98.7654 trillion │
└─────────────┴──────────────────┘

​

formatReadableSize

導入バージョン: v1.1.0

サイズ (バイト数) を指定すると、この関数は接尾辞 (KiB、MiB など) 付きの、読みやすく丸められたサイズを文字列で返します。

この関数の逆の処理を行うのは parseReadableSize、parseReadableSizeOrZero、および parseReadableSizeOrNull です。 この関数は入力として任意の数値型を受け付けますが、内部ではそれらを Float64 にキャストします。値が大きい場合、結果が最適にならないことがあります。

構文

formatReadableSize(value[, precision])

別名: FORMAT_BYTES

引数

• value — バイト単位のサイズ。Int8 または Int16 または Int32 または Int64 または UInt8 または UInt16 または UInt32 または UInt64 または Float32 または Float64 または Decimal
• precision — 任意です。精度です。デフォルトは 2 です。const UInt8

戻り値

接尾辞付きで、読みやすいように丸められたサイズを文字列で返します。String

例

ファイルサイズのフォーマット

Query

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

Response

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

精度を明示的に指定した場合

Query

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

Response

┌─no_decimals─┬─four_decimals─┐
│ 184 MiB     │ 183.9179 MiB  │
└─────────────┴───────────────┘

​

formatReadableTimeDelta

導入バージョン: v20.12.0

秒単位の時間間隔 (delta) または INTERVAL 式が与えられると、この関数は年/月/日/時/分/秒/ミリ秒/マイクロ秒/ナノ秒を含む時間差を文字列で返します。

この関数は任意の数値型を入力として受け付けますが、内部的にはそれらを Float64 にキャストします。値が大きい場合、結果が最適でないことがあります。

INTERVAL 式が渡されると、その値は秒に変換されます。MONTH 以上の interval 単位 (MONTH、QUARTER、YEAR) は、秒単位で固定長の間隔を表さないため、サポートされていません。

構文

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

引数

• column — 数値の時間差を表すカラム、または INTERVAL 式。MONTH 以上の Interval 単位はサポートされていません。Float64 または Interval
• maximum_unit — 任意。表示する最大の単位。有効な値: nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。デフォルト値: years。const String
• minimum_unit — 任意。表示する最小の単位。これより小さい単位はすべて切り捨てられます。有効な値: nanoseconds、microseconds、milliseconds、seconds、minutes、hours、days、months、years。明示的に指定した値が maximum_unit より大きい場合は、例外がスローされます。デフォルト値: maximum_unit が seconds 以上の場合は seconds、それ以外の場合は nanoseconds。const String

戻り値

時間差を文字列として返します。String

例

使用例

Query

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

Response

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

最大単位付き

Query

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

Response

┌───elapsed─┬─time_delta─────────────────────┐
│       100 │ 1 minute and 40 seconds        │
│     12345 │ 205 minutes and 45 seconds     │
│ 432546534 │ 7209108 minutes and 54 seconds │
└───────────┴────────────────────────────────┘

INTERVAL 式を使用する場合

Query

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

Response

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

​

fuzzQuery

導入バージョン: v26.2.0

指定されたクエリ文字列を解析し、ランダムな AST ミューテーション (ファジング) を適用します。ファジングされたクエリを文字列として返します。非決定論的で、呼び出すたびに異なる結果になる場合があります。allow_fuzz_query_functions = 1 が必要です。

構文

fuzzQuery(query)

引数

• query — ファズ対象の SQL クエリ。String

戻り値

ファズ処理されたクエリ文字列 String

例

基本的な例

Query

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

​

generateRandomStructure

導入バージョン: v23.5.0

column1_name column1_type, column2_name column2_type, ... の形式でランダムなテーブルの構造を生成します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

generateRandomStructure([number_of_columns, seed])

引数

• number_of_columns — 生成されるテーブル構造のカラム数。0 または Null に設定すると、カラム数は 1〜128 の範囲でランダムに決まります。デフォルト値: Null。 UInt64
• seed — 再現可能な結果を得るための乱数シード。seed が指定されていないか Null に設定されている場合は、ランダムに生成されます。 UInt64

戻り値

ランダムに生成されたテーブル構造。 String

例

使用例

Query

SELECT generateRandomStructure()

Response

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

指定したカラム数の

Query

SELECT generateRandomStructure(1)

Response

c1 Map(UInt256, UInt16)

指定したシードで

Query

SELECT generateRandomStructure(NULL, 33)

Response

c1 DateTime, c2 Enum8(\'c2V0\' = -123, \'c2V1\' = 94, \'c2V2\' = -105, \'c2V3\' = 67), c3 Nullable(UInt8), c4 String, c5 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(71))), c6 UInt32, c7 Bool, c8 Float64

​

generateSerialID

導入バージョン: v25.1.0

前回のカウンター値に続く連番を生成して返します。 この関数は、文字列の引数 (シリーズ識別子) と、省略可能な開始値を受け取ります。 サーバーは Keeper を使用するように設定する必要があります。 シリーズはパス配下の Keeper ノードに保存され、このパスはサーバー設定の series_keeper_path で設定できます。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

generateSerialID(series_identifier[, start_value])

引数

• series_identifier — シリーズ識別子 const String
• start_value — 任意。カウンターの開始値です。デフォルトは 0 です。注意: この値が使用されるのは新しいシリーズを作成する場合のみで、シリーズがすでに存在する場合は無視されます UInt*

戻り値

直前のカウンター値に続く連番を返します。 UInt64

例

最初の呼び出し

Query

SELECT generateSerialID('id1')

Response

┌─generateSerialID('id1')─┐
│                       0 │
└─────────────────────────┘

2回目の呼び出し

Query

SELECT generateSerialID('id1')

Response

┌─generateSerialID('id1')─┐
│                       1 │
└─────────────────────────┘

カラムの呼び出し

Query

CREATE TABLE test_table (CounterID UInt32, UserID UInt32, ver UInt32) ENGINE = Memory;
INSERT INTO test_table VALUES (1, 3, 3), (1, 1, 1), (1, 2, 2), (1, 5, 5), (1, 4, 4);

SELECT *, generateSerialID('id1') FROM test_table

Response

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')─┐
│         1 │      3 │   3 │                       2 │
│         1 │      1 │   1 │                       3 │
│         1 │      2 │   2 │                       4 │
│         1 │      5 │   5 │                       5 │
│         1 │      4 │   4 │                       6 │
└───────────┴────────┴─────┴─────────────────────────┘

開始値あり

Query

SELECT generateSerialID('id2', 100)

Response

┌─generateSerialID('id2', 100)─┐
│                          100 │
└──────────────────────────────┘

開始値を指定した2回目の呼び出し

Query

SELECT generateSerialID('id2', 100)

Response

┌─generateSerialID('id2', 100)─┐
│                          101 │
└──────────────────────────────┘

​

getClientHTTPHeader

導入バージョン: v24.5.0

HTTP ヘッダーの値を取得します。 該当するヘッダーが存在しない場合、または現在のリクエストが HTTP インターフェイス経由で実行されていない場合、この関数は空文字列を返します。 一部の HTTP ヘッダー (例: Authorization、Authentication および X-ClickHouse-*) には制限があります。

この関数を使用するには、設定 allow_get_client_http_header を有効にする必要があります。 Cookie などの一部のヘッダーには機密情報が含まれる可能性があるため、セキュリティ上の理由からこの設定はデフォルトで無効になっています。

RFC 9110 に従い、HTTP ヘッダーでは大文字と小文字は区別されません。 この関数を分散クエリ内で使用した場合、空でない結果を返すのはイニシエーターノード上のみです。

getClientHTTPHeader は現在のリクエストのヘッダーを読み取るため、クエリが HTTP インターフェイス経由で送信された場合にのみ空でない値を返します。 たとえば、リクエストにヘッダーを付与し、HTTP 経由でその値を読み取れます。

echo "SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1" | \
    curl 'http://localhost:8123/' --data-binary @- -H 'Content-Type: application/x-www-form-urlencoded'

上記のコマンドを実行すると、application/x-www-form-urlencoded が返されます。

構文

getClientHTTPHeader(name)

引数

• name — HTTP ヘッダー名。String

戻り値

ヘッダーの値を返します。String

例

使用例

Query

-- Over a non-HTTP interface (such as `clickhouse-client` or `clickhouse-local`) there are
-- no request headers, so the function returns an empty string. See the description above
-- for an HTTP example that returns the actual header value.
SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1

​

getMacro

導入バージョン: v20.1.0

サーバー設定ファイルからマクロの値を返します。 マクロは設定ファイルの<macros>セクションで定義され、ホスト名が複雑な場合でも、わかりやすい名前でサーバーを識別するために使用できます。 この関数を分散テーブルのコンテキストで実行すると、各分片に対応する値を持つ通常のカラムが生成されます。

そのテーブルを読み取る場合と同様に、system.macros に対する SELECT 権限が必要です。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

getMacro(name)

引数

• name — 取得するマクロの名前。const String

戻り値

指定したマクロの値を返します。String

例

基本的な使い方

Query

SELECT getMacro('test');

Response

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

​

getMaxTableNameLengthForDatabase

導入バージョン: v25.1.0

指定したデータベース内のテーブル名の最大長を返します。

構文

getMaxTableNameLengthForDatabase(database_name)

引数

• database_name — 指定したデータベースの名前。String

戻り値

最大のテーブル名の長さを表す整数値を返します

例

一般的な例

Query

SELECT getMaxTableNameLengthForDatabase('default');

Response

┌─getMaxTableNameLengthForDatabase('default')─┐
│                                         206 │
└─────────────────────────────────────────────┘

​

getMergeTreeSetting

導入バージョン: v25.6.0

MergeTree設定の現在の値を返します。

このテーブルを読み取る場合と同様に、system.merge_tree_settings に対する SELECT 権限が必要です。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

getMergeTreeSetting(setting_name)

引数

• setting_name — 設定名。 String

戻り値

MergeTree 設定の現在の値を返します。

例

使用例

Query

SELECT getMergeTreeSetting('index_granularity');

Response

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

​

getOSKernelVersion

導入バージョン: v21.11.0

OS カーネルのバージョンを含む文字列を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

getOSKernelVersion()

引数

• なし

戻り値

現在の OS カーネルのバージョンを返します。 String

例

使用例

Query

SELECT getOSKernelVersion();

Response

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

​

getServerPort

導入バージョン: v21.10.0

指定したプロトコルのサーバーのポート番号を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

getServerPort(port_name)

引数

• port_name — ポート名。String

戻り値

サーバーのポート番号を返します。UInt16

例

使用例

Query

SELECT getServerPort('tcp_port');

Response

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

​

getServerSetting

導入バージョン: v25.6.0

サーバー設定名を指定すると、現在設定されている値を返します。

このテーブルを直接読み取る場合と同様に、system.server_settings に対する SELECT 権限が必要です。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

getServerSetting(setting_name')

引数

• setting_name — サーバー設定名。String

戻り値

サーバー設定の現在の値を返します。Any

例

使用例

Query

SELECT getServerSetting('allow_use_jemalloc_memory');

Response

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

​

getSetting

導入バージョン: v20.7.0

設定の現在の値を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

getSetting(setting_name)

引数

• setting_Name — 設定名。 const String

戻り値

設定の現在の値を返します。 Any

例

使用例

Query

SET optimize_move_to_prewhere = false;
SELECT getSetting('optimize_move_to_prewhere');
SET optimize_move_to_prewhere = true;
SELECT getSetting('optimize_move_to_prewhere');

Response

┌─getSetting('optimize_move_to_prewhere')─┐
│ false                                   │
└─────────────────────────────────────────┘
┌─getSetting('optimize_move_to_prewhere')─┐
│ true                                    │
└─────────────────────────────────────────┘

​

getSettingOrDefault

導入バージョン: v24.10.0

設定の現在の値を返します。現在のプロファイルでその設定が指定されていない場合は、2 番目の引数で指定されたデフォルト値を返します。

この関数は非決定論的です。同じ引数でも、異なる結果を返すことがあります。

構文

getSettingOrDefault(setting_name, default_value)

引数

• setting_name — 設定名。String
• default_value — custom_setting が設定されていない場合に返される値。値には任意のデータ型または Null を指定できます。

戻り値

指定した設定の現在の値を返します。設定されていない場合は default_value を返します。

例

使用例

Query

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

Response

my_value
100
\N

​

getSizeOfEnumType

導入バージョン: v1.1.0

指定されたEnumに含まれるフィールドの数を返します。

構文

getSizeOfEnumType(x)

引数

• x — Enum 型の値。Enum

戻り値

Enum 型の入力値を持つフィールドの数を返します。UInt8/16

例

使用例

Query

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

Response

┌─x─┐
│ 2 │
└───┘

​

getSubcolumn

導入バージョン: v23.3.0

式または識別子と、サブカラム名を表す定数文字列を受け取ります。

式から抽出した指定のサブカラムを返します。

構文

getSubcolumn(nested_value, subcolumn_name)

引数

• なし。

戻り値

例

getSubcolumn

Query

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')
FROM values('array_col Array(UInt32), tuple_col Tuple(elem_name String)', ([1, 2, 3], tuple('abc')));

Response

┌─getSubcolumn(array_col, 'size0')─┬─getSubcolumn(tuple_col, 'elem_name')─┐
│                                3 │ abc                                  │
└──────────────────────────────────┴──────────────────────────────────────┘

​

getTypeSerializationStreams

導入バージョン: v22.6.0

データ型のストリームパスを列挙します。 この関数は開発目的での使用を想定しています。

構文

getTypeSerializationStreams(col)

引数

• col — データ型を検出する対象の、カラム、またはデータ型の文字列表現。Any

戻り値

すべてのシリアライゼーションのサブストリームパスを含む配列を返します。Array(String)

例

tuple

Query

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

Response

['{TupleElement(1), InlinedStringSizes()}','{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), InlinedStringSizes()}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

map

Query

SELECT getTypeSerializationStreams('Map(String, Int64)')

Response

['{ArraySizes}','{ArrayElements, TupleElement(keys), InlinedStringSizes()}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

​

globalVariable

導入バージョン: v20.5.0

定数の文字列引数を受け取り、その名前を持つグローバル変数の値を返します。この関数は MySQL との互換性のためのもので、ClickHouse の通常の運用では必要でも有用でもありません。定義されているダミーのグローバル変数はごくわずかです。

構文

globalVariable(name)

引数

• name — グローバル変数の名前。String

戻り値

変数 name の値を返します。Any

例

globalVariable

Query

SELECT globalVariable('max_allowed_packet')

Response

67108864

​

hasColumnInTable

導入バージョン: v1.1.0

データベース内のテーブルに特定のカラムが存在するかどうかを確認します。 ネストされたデータ構造内の要素については、この関数はカラムの存在を確認します。 ネストされたデータ構造そのものに対しては、この関数は 0 を返します。

この関数を使用するには、ターゲットテーブルに対する SHOW COLUMNS 権限が必要です (DESCRIBE および SHOW CREATE TABLE に必要な権限と同じです) 。 この権限がない場合、呼び出しは 1 または 0 を返すのではなく ACCESS_DENIED で失敗するため、アクセス権がない状態でカラム名の有無を調べることはできません。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

hasColumnInTable(database, table, column)

引数

• database — データベース名。const String
• table — テーブル名。const String
• column — カラム名。const String

戻り値

指定したカラムが存在する場合は 1、存在しない場合は 0 を返します。UInt8

例

既存のカラムを確認する

Query

SELECT hasColumnInTable('system','metrics','metric')

Response

1

存在しないカラムをチェックする

Query

SELECT hasColumnInTable('system','metrics','non-existing_column')

Response

0

​

hasThreadFuzzer

導入バージョン: v20.6.0

thread fuzzer が有効になっているかどうかを返します。 この関数は、テストとデバッグにのみ有用です。

構文

hasThreadFuzzer()

引数

• なし。

戻り値

Thread Fuzzer が有効になっているかどうかを返します。UInt8

例

Thread Fuzzer の状態を確認する

Query

SELECT hasThreadFuzzer()

Response

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

​

highlightQuery

導入バージョン: v26.5.0

ClickHouse SQLのクエリ文字列を解析し、構文ハイライト用の範囲の配列を返します。 各範囲は、開始位置 (バイト単位) 、終了位置、ハイライトの種類を含む名前付きタプルです。 ハイライトの種類は、その部分の構文上の役割 (キーワード、識別子、関数など) を表し、 UIで色を割り当てるために使用できます。LIKE および REGEXP の文字列パターン内では、メタ文字 とエスケープ文字は個別にハイライトされます。

構文

highlightQuery(query)

引数

• query — ClickHouse SQLのクエリ文字列。String。

戻り値

ハイライトされた範囲を表す、名前付きタプル (begin UInt64, end UInt64, type Enum8(...)) の配列。Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

例

シンプル

Query

SELECT highlightQuery('SELECT 1')

Response

[(0,6,'keyword'),(7,8,'number')]

​

hostName

導入バージョン: v20.5.0

この関数が実行されたホスト名を返します。 関数がリモートサーバー上で実行される場合 (分散処理) 、そのリモートサーバー名が返されます。 関数が分散テーブルのコンテキストで実行される場合は、各分片に対応する値を持つ通常のカラムを生成します。 それ以外の場合は、定数値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

hostName()

別名: hostname

引数

• ありません。

戻り値

ホスト名を返します。String

例

使用例

Query

SELECT hostName()

Response

┌─hostName()─┐
│ clickhouse │
└────────────┘

​

icebergBucket

導入バージョン: v25.5.0

iceberg bucket transformのロジックを実装しています。

構文

icebergBucket(N, value)

引数

• N — バケット数 (法) 。const (U)Int*
• value — 変換元の値。(U)Int* または Bool または Decimal または Float* または String または FixedString または UUID または Date または Time または DateTime

戻り値

変換元の値の 32 ビットハッシュを返します。Int32

例

例

Query

SELECT icebergBucket(5, 1.0 :: Float32)

Response

4

​

icebergDay

導入バージョン: v26.9.0

Iceberg の day パーティション変換を実装します。UTC で計算した、1970-01-01 からの日数を返します。 https://iceberg.apache.org/spec/#partition-transforms を参照してください。

構文

icebergDay(value)

引数

• value — 変換する値。Date、Date32、DateTime、または DateTime64

戻り値

1970-01-01 からの日数。1970 年より前の値の場合は負の値になります。 Int32

例

例

Query

SELECT icebergDay(toDate32('1969-12-31'))

Response

-1

​

icebergHour

導入バージョン: v26.9.0

Iceberg の hour パーティション変換を実装します。1970-01-01 00:00:00 からの経過時間数 (UTC で計算) を返します。 https://iceberg.apache.org/spec/#partition-transforms を参照してください。

構文

icebergHour(value)

引数

• value — 変換する値。DateTime または DateTime64

戻り値

1970-01-01 00:00:00 からの時間数。1970 年より前の値の場合は負の値 Int32

例

例

Query

SELECT icebergHour(toDateTime64('1970-01-01 01:30:00', 6, 'UTC'))

Response

1

​

icebergMonth

導入バージョン: v26.9.0

Iceberg の month パーティション変換を実装します。1970-01-01 からの月数を UTC で計算します。 https://iceberg.apache.org/spec/#partition-transforms を参照してください。

構文

icebergMonth(value)

引数

• value — 変換する値。Date、Date32、DateTime、または DateTime64

戻り値

1970-01-01 からの月数。1970 年より前の値の場合は負の値 Int32

例

例

Query

SELECT icebergMonth(toDate32('1969-01-01'))

Response

-12

​

icebergTruncate

導入バージョン: v25.3.0

Iceberg の truncate transform のロジックを実装しています: https://iceberg.apache.org/spec/#truncate-transform-details.

構文

icebergTruncate(N, value)

引数

• value — 変換対象の値。String または (U)Int* または Decimal

戻り値

引数と同じ型

例

例

Query

SELECT icebergTruncate(3, 'iceberg')

Response

ice

​

icebergYear

導入バージョン: v26.9.0

Iceberg の year パーティション変換を実装します。UTC で計算した、1970 年からの経過年数を返します。 https://iceberg.apache.org/spec/#partition-transforms を参照してください。

構文

icebergYear(value)

引数

• value — 変換する値。Date、Date32、DateTime、または DateTime64

戻り値

1970年からの経過年数。1970年より前の値の場合は負の値になります。 Int32

例

例

Query

SELECT icebergYear(toDate32('1969-05-05'))

Response

-1

​

identity

導入バージョン: v1.1.0

この関数は、渡された引数をそのまま返します。デバッグやテストに便利です。これを使うと、索引の使用を回避して、代わりにフルスキャンのパフォーマンスを確認できます。クエリアナライザは、使用する索引を探す際に identity 関数内の内容をすべて無視し、定数畳み込みも無効にします。

構文

identity(x)

引数

• x — 入力値。Any

戻り値

入力値をそのまま返します。Any

例

使用例

Query

SELECT identity(42)

Response

42

​

ignore

導入バージョン: v1.1.0

任意の引数を受け取り、常に 0 を返します。

構文

ignore(x)

引数

• x — 構文エラーを回避するためだけに渡され、実際には使用されない入力値です。Any

戻り値

常に 0 を返します。UInt8

例

使用例

Query

SELECT ignore(0, 'ClickHouse', NULL)

Response

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

​

indexHint

導入バージョン: v1.1.0

この関数は、デバッグと内部診断を目的としています。 引数は無視され、常に 1 を返します。 引数は評価されません。

索引解析では、この関数の引数は indexHint でラップされていないものとして扱われます。 これにより、対応する条件に基づいて索引範囲内のデータを選択できますが、その条件による追加の絞り込みは行われません。 ClickHouse の索引はスパースであるため、indexHint を使用すると、同じ条件を直接指定した場合よりも多くのデータが返されます。

説明

次を実行すると:

SELECT * FROM test WHERE key = 123;

ClickHouse は次の 2 つを行います:

1. 索引を使って、key = 123 を含む可能性のあるグラニュール (約 8192 行のブロック) を見つける
2. それらのグラニュールを読み取り、key = 123 の行だけを返すように行ごとにフィルタする

そのため、ディスクから 8,192 行を読み取っても、実際に一致する 1 行だけが返されます。

一方、indexHint を使って次を実行すると:

SELECT * FROM test WHERE indexHint(key = 123);

ClickHouse が行うのは 1 つだけです:

1. 索引を使って key = 123 を含む可能性のあるグラニュールを見つけ、それらのグラニュールから フィルタせずに すべての行を返す

key = 456 や key = 789 などの行も含め、8,192 行すべてが返されます。 (同じグラニュールにたまたま格納されていたものがすべて返されます。) indexHint() はパフォーマンスのためのものではありません。これは、ClickHouse の索引がどのように機能するかをデバッグし、理解するためのものです:

• 自分の条件はどのグラニュールを選択しているか
• それらのグラニュールには何行あるか
• 自分の索引は効果的に使われているか

注: indexHint 関数を使ってクエリを最適化することはできません。indexHint 関数はクエリ分析に追加情報を与えないため、クエリを最適化しません。indexHint 関数の中に式を入れても、indexHint 関数を使わない場合と比べて何ら有利ではありません。indexHint 関数は内部診断とデバッグの目的でのみ使用でき、パフォーマンスを改善するものではありません。ClickHouse のコントリビューター以外が indexHint を使っているのを見かけた場合、それはおそらく誤りなので削除すべきです。

構文

indexHint(expression)

引数

• expression — 索引範囲の選択に使用する任意の式。式

戻り値

常に 1 を返します。UInt8

例

日付でフィルタリングする使用例

Query

-- `index_granularity` is lowered to 8 here only to keep the example small enough to follow.
-- Do not change it in production: the default of 8192 is what makes the index sparse and cheap,
-- and a small value makes the index large and slows queries down.
CREATE TABLE ontime (FlightDate Date, Carrier String)
ENGINE = MergeTree ORDER BY FlightDate
SETTINGS index_granularity = 8;

-- Ten flights on each of four days, so a granule of eight rows spans more than one day.
INSERT INTO ontime SELECT toDate('2025-09-14') + intDiv(number, 10), 'AA' FROM numbers(40);

-- The granules that hold the rows of 2025-09-15 also hold rows of the neighbouring days,
-- and `indexHint` returns all of them.
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

Response

┌──────────k─┬─count()─┐
│ 2025-09-14 │       2 │
│ 2025-09-15 │      10 │
│ 2025-09-16 │       4 │
└────────────┴─────────┘

​

initialQueryID

導入バージョン: v1.1.0

現在の初期クエリの ID を返します。 クエリのその他のパラメータは、system.query_log の initial_query_id フィールドから取得できます。

queryID 関数とは異なり、initialQueryID は異なる分片でも同じ結果を返します。

この関数は非決定論的です。同じ引数に対しても異なる結果を返す場合があります。

構文

initialQueryID()

別名: initial_query_id

引数

• なし。

戻り値

現在の初期クエリの ID を返します。String

例

使用例

Query

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());

Response

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

​

initialQueryStartTime

導入バージョン: v25.4.0

現在の初期クエリの開始時刻を返します。 initialQueryStartTime は、異なる分片でも同じ結果を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

initialQueryStartTime()

別名: initial_query_start_time

引数

• なし。

戻り値

現在の初期クエリの開始時刻を返します。DateTime

例

使用例

Query

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

Response

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

​

initializeAggregation

導入バージョン: v20.6.0

単一の値に基づいて、集約関数の結果を計算します。 この関数は、-State コンビネータを持つ集約関数を初期化するために使用できます。 集約関数の状態を作成して、それを AggregateFunction 型のカラムに挿入したり、初期化された集約をデフォルト値として使用したりできます。

Syntax

initializeAggregation(aggregate_function, arg1[, arg2, ...])

引数

• aggregate_function — 初期化する集約関数の名前。 String
• arg1[, arg2, ...] — 集約関数の引数。 Any

戻り値

関数に渡された各行について、集約結果を返します。戻り値の型は、initializeAggregation の第1引数として指定する関数の戻り値の型と同じです。 Any

例

uniqState を使った基本的な使い方

Query

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

Response

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

sumState と finalizeAggregation の使用

Query

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

Response

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

​

isConstant

導入バージョン: v20.3.0

引数が定数式であるかどうかを返します。 定数式とは、その結果がクエリ分析中、つまり実行前に確定している式です。 たとえば、リテラルからなる式は定数式です。 この関数は主に、開発、デバッグ、デモンストレーションを目的としています。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

isConstant(x)

引数

• x — 確認する式。Any

戻り値

x が定数であれば 1、定数でなければ 0 を返します。UInt8

例

定数式

Query

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

Response

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

関数を伴う定数

Query

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

Response

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

非定数式

Query

SELECT isConstant(number)
FROM numbers(1)

Response

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

now() 関数の動作

Query

SELECT isConstant(now())

Response

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

​

isDecimalOverflow

導入バージョン: v20.8.0

10進数が、指定された精度の Decimal データ型に収まるには桁数が多すぎるかどうかを判定します。

構文

isDecimalOverflow(value[, precision])

引数

• value — チェック対象の Decimal 値。Decimal
• precision — 任意。Decimal 型の精度です。省略した場合は、最初の引数の元の精度が使用されます。UInt8

戻り値

Decimal 値の桁数がその精度で許容される桁数を超えている場合は 1、指定された精度を満たしている場合は 0 を返します。UInt8

例

使用例

Query

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

Response

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

​

joinGet

導入バージョン: v18.16.0

Dictionary と同様に、テーブルからデータを取得できます。 指定した結合キーを使って Join テーブルからデータを取得します。

ENGINE = Join(ANY, LEFT, <join_keys>) ステートメント で作成されたテーブルのみサポートしています。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

joinGet(join_storage_table_name, value_column, join_keys)

引数

• join_storage_table_name — 検索対象を示す識別子です。この識別子はデフォルトデータベース内で検索されます (設定ファイルのパラメータ default_database を参照) 。デフォルトデータベースを変更するには、USE database_name クエリを使用するか、database_name.table_name のようにデータベース名とテーブル名をドットで指定します。String
• value_column — 必要なデータを含むtableのカラム名です。const String
• join_keys — 結合キーのリストです。Any

戻り値

キーのリストに対応する値のリストを返します。Any

例

使用例

Query

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(id_val, 'val', toUInt32(1));

Response

┌─joinGet('id_val', 'val', toUInt32(1))─┐
│                                    11 │
└───────────────────────────────────────┘

現在のデータベース内のテーブルを使用する場合

Query

SELECT joinGet(id_val, 'val', toUInt32(2));

Response

┌─joinGet('id_val', 'val', toUInt32(2))─┐
│                                    12 │
└───────────────────────────────────────┘

結合キーとしてArrayを使用する

Query

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', toUInt32(1), toUInt32(11));

Response

┌─joinGet('some_table', 'name', toUInt32(1), toUInt32(11))─┐
│ a                                                        │
└──────────────────────────────────────────────────────────┘

​

joinGetOrNull

導入バージョン: v20.4.0

Dictionary と同様の方法で、テーブルからデータを取得できます。 指定した結合キーを使用して Join テーブルからデータを取得します。 joinGet とは異なり、キーが存在しない場合は NULL を返します。

ENGINE = Join(ANY, LEFT, <join_keys>) ステートメント で作成されたテーブルのみサポートします。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

joinGetOrNull(join_storage_table_name, value_column, join_keys)

引数

• join_storage_table_name — 検索を実行する場所を指定する識別子です。この識別子はデフォルトデータベース内で検索されます (設定ファイルの default_database パラメータを参照) 。デフォルトデータベースを変更するには、USE database_name クエリを使用するか、database_name.table_name のようにドット区切りでデータベース名とテーブル名を指定します。String
• value_column — 必要なデータを含むテーブルのカラム名です。const String
• join_keys — 結合キーのリストです。Any

戻り値

キーのリストに対応する値のリストを返します。キーが見つからない場合は NULL を返します。Any

例

使用例

Query

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(id_val, 'val', toUInt32(1)), joinGetOrNull(id_val, 'val', toUInt32(999));

Response

┌─joinGetOrNull('id_val', 'val', toUInt32(1))─┬─joinGetOrNull('id_val', 'val', toUInt32(999))─┐
│                                          11 │                                          ᴺᵁᴸᴸ │
└─────────────────────────────────────────────┴───────────────────────────────────────────────┘

​

lowCardinalityIndices

導入バージョン: v18.12.0

LowCardinality カラムのDictionary内での値の位置を返します。位置は 1 から始まります。LowCardinality ではパーツごとにDictionaryが作成されるため、この関数はパーツが異なると同じ値に対しても異なる位置を返す場合があります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

lowCardinalityIndices(col)

引数

• col — 低カーディナリティのカラム。LowCardinality

戻り値

現在のパーツの Dictionary 内における値の位置。UInt64

例

使用例

Query

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

-- the order the blocks are read in is not defined, so sort the result to make it reproducible:

SELECT s, lowCardinalityIndices(s) AS index FROM test ORDER BY s, index;

Response

┌─s──┬─index─┐
│ ab │     1 │
│ ab │     1 │
│ ab │     1 │
│ ab │     3 │
│ cd │     2 │
│ cd │     2 │
│ cd │     2 │
│ df │     3 │
│ ef │     1 │
│ ef │     1 │
└────┴───────┘

​

lowCardinalityKeys

導入バージョン: v18.12.0

LowCardinality カラムのDictionary値を返します。 ブロックがDictionaryサイズより小さい、または大きい場合、結果は切り詰められるか、デフォルト値で拡張されます。 LowCardinality はパーツごとにDictionaryを持つため、この関数はパーツによって異なるDictionary値を返す場合があります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

lowCardinalityKeys(col)

引数

• col — 低カーディナリティのカラムです。LowCardinality

戻り値

Dictionaryキーを返します。UInt64

例

lowCardinalityKeys

Query

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

Response

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

​

materialize

導入バージョン: v1.1.0

定数を、単一の値を含むフルカラムに変換します。 フルカラムと定数は、メモリ内では異なる形で表現されます。 関数は通常、通常の引数と定数引数に対して異なるコードを実行しますが、結果は一般に同じになるはずです。 この関数は、この動作をデバッグするために使用できます。

構文

materialize(x)

引数

• x — 定数。Any

戻り値

定数値を含む通常のカラムを返します。Any

例

使用例

Query

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

SELECT countMatches('foobarfoo', 'foo');

Response

2

定数をフルカラムに変換する

Query

SELECT countMatches('foobarfoo', materialize('foo'));

Response

Received exception:
Code: 44. DB::Exception: A value of illegal type was provided as 2nd argument 'pattern' to function 'countMatches'. Expected: constant String, got: String. (ILLEGAL_COLUMN)

​

minSampleSizeContinuous

導入バージョン: v23.10.0

2 つのサンプルにおける連続値メトリクスの平均を比較する A/B テストに必要な最小サンプルサイズを計算します。

この記事で説明されている式を使用します。 介入群と対照群のサイズが等しいことを前提としています。 1 グループあたりに必要なサンプルサイズを返します (つまり、実験全体で必要なサンプルサイズは戻り値の 2 倍です) 。 また、テスト対象メトリクスの分散が介入群と対照群で等しいことも前提としています。

構文

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

別名: minSampleSizeContinous

引数

• baseline — メトリックのベースライン値。 (U)Int* または Float*
• sigma — メトリックのベースライン標準偏差。 (U)Int* または Float*
• mde — ベースライン値に対する割合としての最小検出効果 (MDE) (例: ベースライン値が 112.25 の場合、MDE が 0.03 であれば、112.25 ± 112.25*0.03 への変化を想定します) 。 (U)Int* または Float*
• power — テストに必要な統計的検出力 (1 - 第 II 種過誤の確率) 。 (U)Int* または Float*
• alpha — テストに必要な有意水準 (第 I 種過誤の確率) 。 (U)Int* または Float*

戻り値

3 つの要素 minimum_sample_size、detect_range_lower、detect_range_upper を持つ名前付き Tuple を返します。これらはそれぞれ、必要なサンプルサイズ、返される必要サンプルサイズでは検出できない値の範囲の下限 (baseline * (1 - mde) として計算) 、および返される必要サンプルサイズでは検出できない値の範囲の上限 (baseline * (1 + mde) として計算) です (Float64) 。 Tuple(Float64, Float64, Float64)

例

minSampleSizeContinuous

Query

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

Response

(616.2931945826209,108.8825,115.6175)

​

minSampleSizeConversion

導入バージョン: v22.6.0

2 つのサンプルにおけるコンバージョン率 (比率) を比較する A/B テストで、必要な最小サンプルサイズを計算します。

この記事で説明されている式を使用します。介入群と対照群のサイズが等しいことを前提としています。戻り値は一方のグループに必要なサンプルサイズです (つまり、実験全体に必要なサンプルサイズはこの戻り値の 2 倍です) 。

構文

minSampleSizeConversion(baseline, mde, power, alpha)

引数

• baseline — ベースラインのコンバージョン率。Float*
• mde — パーセンテージポイントで表した最小検出可能効果 (MDE) 。 (例: ベースラインのコンバージョン率が 0.25 の場合、MDE が 0.03 であれば、0.25 ± 0.03 への変化を想定します。) Float*
• power — テストで必要な統計的検出力 (1 - 第 II 種過誤の確率) 。Float*
• alpha — テストで必要な有意水準 (第 I 種過誤の確率) 。Float*

戻り値

3 つの要素 minimum_sample_size、detect_range_lower、detect_range_upper を持つ名前付きTupleを返します。これらはそれぞれ、必要なサンプルサイズ、返される必要サンプルサイズでは検出できない値の範囲の下限 (baseline - mde として計算) 、返される必要サンプルサイズでは検出できない値の範囲の上限 (baseline + mde として計算) を表します。Tuple(Float64, Float64, Float64)

例

minSampleSizeConversion

Query

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

Response

(3396.077603219163,0.22,0.28)

​

neighbor

導入バージョン: v20.1.0

現在の行から指定したオフセット位置にあるカラムの値を返します。 この関数は非推奨です。data block の物理的な順序に基づいて動作するため、ユーザーが想定する論理的な順序と一致しない可能性があり、エラーを引き起こしやすくなっています。 代わりに、適切なウィンドウ関数の使用を検討してください。

この関数は、allow_deprecated_error_prone_window_functions = 1 を設定することで有効にできます。

構文

neighbor(column, offset[, default_value])

引数

• column — 対象のカラム。Any
• offset — 現在の行からのオフセット。正の値は後方を、負の値は前方を参照します。Integer
• default_value — 任意。オフセットがデータ範囲外になった場合に返す値です。指定しない場合は、カラム型のデフォルト値が使用されます。Any

戻り値

指定したオフセット位置の値を返します。範囲外の場合はデフォルト値を返します。Any

例

使用例

Query

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

Response

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

デフォルト値あり

Query

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

Response

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

​

normalizeQuery

導入バージョン: v20.8.0

リテラル、リテラルの並び、および複雑な別名 (空白を含むもの、3 桁以上の数字を含むもの、または UUID のように 36 バイト以上の長さを持つもの) をプレースホルダー ? に置き換えます。

構文

normalizeQuery(x)

引数

• x — 文字列。String

戻り値

プレースホルダーに置き換えた指定の文字列を返します。String

例

使用例

Query

SELECT normalizeQuery('[1, 2, 3, x]') AS query

Response

┌─query────┐
│ [?.., x] │
└──────────┘

​

normalizeQueryKeepNames

導入バージョン: v21.2.0

リテラルおよびリテラルの並びをプレースホルダー ? に置き換えますが、複雑な別名 (空白を含むもの、3 桁以上の数字を含むもの、または UUID などのように 36 バイト以上の長さを持つもの) は置き換えません。 これにより、複雑なクエリログをより適切に分析しやすくなります。

構文

normalizeQueryKeepNames(x)

引数

• x — 文字列。String

戻り値

指定された文字列をプレースホルダー付きで返します。String

例

使用例

Query

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

Response

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

​

normalizedQueryHash

導入バージョン: v20.8.0

類似したクエリに対して、リテラル値を除外した同一の64ビットハッシュ値を返します。 クエリログの分析に役立ちます。

構文

normalizedQueryHash(x)

引数

• x — 文字列。String

戻り値

64ビットのハッシュ値を返します。UInt64

例

使用例

Query

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

Response

┌─res─┐
│   1 │
└─────┘

​

normalizedQueryHashKeepNames

導入バージョン: v21.2.0

normalizedQueryHash と同様に、類似したクエリに対してはリテラル値を除いた同一の64ビットのハッシュ値を返しますが、ハッシュ化の前に複雑な別名 (空白を含む、3桁以上の数字を含む、または UUID のように36バイト以上の長さがあるもの) をプレースホルダーに置き換えることはありません。 クエリログの分析に役立ちます。

構文

normalizedQueryHashKeepNames(x)

引数

• x — 文字列。String

戻り値

64 ビットのハッシュ値を返します。UInt64

例

使用例

Query

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

Response

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

​

obfuscateQuery

導入バージョン: v26.4.0

識別子をランダムな単語に、リテラルをランダムな値に置き換えつつ、クエリ構造を維持したまま SQL クエリを難読化します。

この関数は、デバッグ目的でクエリをログに記録したり共有したりする前に、クエリを匿名化するのに役立ちます。 同じ入力クエリであっても、行が異なれば異なる難読化結果が生成されるため、 複数のクエリを扱う際のプライバシー保護に役立ちます。

オプションの tag パラメータは、同じ関数呼び出しが 1 つのクエリ内で複数回使われる場合に、共通部分式除去を防ぎます。これにより、呼び出しごとに異なる難読化結果が生成されます。

特長:

• テーブル名、カラム名、別名をランダムな単語に置き換えます
• 数値リテラルと文字列リテラルをランダムな値に置き換えます
• クエリ全体の構造と SQL 構文を保持します
• 行ごとに異なる結果を生成します

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

obfuscateQuery(query[, tag])

引数

• query — 難読化する SQL クエリ。String
• tag — 任意。同じ関数呼び出しが複数回使用される場合に、共通部分式除去を防ぐための値です。

戻り値

識別子とリテラルを置き換えつつ、元のクエリ構造を保持した難読化済みクエリ。String

例

基本的な使い方

Query

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

Response

SELECT fruit, number FROM table WHERE number > 12

共通部分式除去を防ぐためのタグ付き

Query

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

Response

SELECT a FROM b, SELECT c FROM d

行が異なると結果も異なります

Query

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

Response

SELECT 1	SELECT 1

​

obfuscateQueryWithSeed

導入バージョン: v26.4.0

指定した seed を使って SQL クエリを難読化し、決定論的な結果を得られます。

obfuscateQuery() とは異なり、この関数は同じ seed を指定すると常に同じ結果を返します。 そのため、複数回の実行にわたって一貫した難読化が必要な場合や、 テストやデバッグのために同じ難読化済みクエリを再現したい場合に役立ちます。

特徴:

• 指定した seed に基づく決定論的な難読化
• 同じ seed からは常に同じ難読化結果を生成
• 異なる seed からは異なる結果を生成
• obfuscateQuery() と同様にクエリの構造を保持

使用例:

• 再現可能なテストケース
• 複数回の実行で一貫した匿名化
• 一貫した難読化済みクエリを用いたデバッグ

構文

obfuscateQueryWithSeed(query, seed)

引数

• query — 難読化する SQL クエリ。 String
• seed — 難読化に使用するシード。同じシードを指定すると、決定論的な結果が生成されます。 Integer または String

戻り値

指定したシードに基づいて決定論的に生成された、難読化済みのクエリ。 String

例

整数シードを使用した決定論的な難読化

Query

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

Response

SELECT name FROM users

文字列シードによる決定論的な難読化

Query

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

Response

SELECT id, value FROM data

同じシードなら同じ結果になる

Query

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

Response

1

​

parseISO8601Duration

導入バージョン: v26.9.0

ISO 8601 duration 文字列を解析し、秒数を返します。

期間は P で始まり、その後に任意の日付部分が続き、さらに T で始まる任意の時刻セクションが続きます。

• W - 週
• D - 日
• T - 時刻セクションの開始
• H - 時
• M - 分 (T の後のみ)
• S - 秒

ISO 8601 では最下位の部分にのみ小数部が認められますが、ここではどの部分にも小数部を指定できます。そのため PT0.5H は有効で、1800 を返します。

指示子は上記の順序で記述する必要があり、それぞれ最大 1 回までしか使用できません。ISO 8601:2004 では週の指示子は排他的ですが、ここでは他の指示子と組み合わせられます。

年 (Y) の指示子と、T より前の月 (M) の指示子は拒否されます。年も月も秒数として固定の長さを持たないためです。こうした期間は、基準日を用いて変換してください。

規格およびその拡張機能では許容されている次の 2 つの形式は受け付けられません。

• PT1,5S のように小数点の区切りにカンマを使う形式 - ピリオドを使用してください
• -PT1S のような先頭の符号。これはコア文法ではなく RFC 3339 および XML Schema に由来するものです

Float64 に収まらない値は、無限大として返されるのではなく拒否されます。

Syntax

parseISO8601Duration(duration)

Arguments

• duration — ISO 8601 形式の期間文字列。String

戻り値

秒数。Float64

Examples

Usage example

Query

SELECT parseISO8601Duration('PT1H30M')

Response

┌─parseISO8601Duration('PT1H30M')─┐
│                            5400 │
└─────────────────────────────────┘

小数秒

Query

SELECT parseISO8601Duration('P1DT12H30M5.5S')

Response

┌─parseISO8601Duration('P1DT12H30M5.5S')─┐
│                               131405.5 │
└────────────────────────────────────────┘

​

parseQueryToJSON

導入バージョン: v26.8.0

SQLクエリ文字列をAST (Abstract Syntax Tree) にパースし、そのツリーのJSON表現を返します。 生成されたJSONは、formatQueryFromJSONに渡してSQLクエリを再構築したり、dialect設定にclickhouse_jsonを指定して直接サーバーに送信したりできます (enable_json_ast_dialectによって制御されます) 。

これは、SQL文法を介さずにプログラムからクエリを検査または変換したいツールで役立ちます。

すべてのSQLクエリが忠実なJSON表現を持つわけではありません。JSON形式では再現できないデータを含むクエリ (たとえばインラインのINSERT ... VALUES / INSERT ... FORMATデータ) や、JSONシリアライゼーションがまだ実装されていない ASTノード型は、formatQueryFromJSONで読み戻せないJSONを生成するのではなく、BAD_ARGUMENTSで拒否されます。

パース制限 (max_query_size、max_parser_depth、max_parser_backtracks) は、現在の セッション設定から取得されます。

構文

parseQueryToJSON(sql)

引数

• sql — 解析するSQLクエリ文字列。String

戻り値

ASTを表すJSON文字列。String

例

単純なSELECT

Query

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT 1'));

Response

┌─formatQueryFromJSON(parseQueryToJSON('SELECT 1'))─┐
│ SELECT 1                                          │
└───────────────────────────────────────────────────┘

​

parseReadableSize

導入バージョン: v24.6.0

バイトサイズを表す文字列と、その単位として B、KiB、KB、MiB、MB など (つまり ISO/IEC 80000-13 または 10 進バイト単位) が与えられると、この関数は対応するバイト数を返します。 この関数が入力値を解析できない場合は、例外をスローします。

この関数の逆演算は formatReadableSize と formatReadableDecimalSize です。

構文

parseReadableSize(x)

引数

• x — ISO/IEC 80000-13 または 10 進のバイト単位を使用した、読みやすいサイズ表記。String

戻り値

最も近い整数に切り上げられたバイト数を返します。UInt64

例

使用例

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

​

parseReadableSizeOrNull

導入バージョン: v24.6.0

バイトサイズを表す文字列と、その単位として B、KiB、KB、MiB、MB など (つまり ISO/IEC 80000-13 または10進のバイト単位) を受け取り、対応するバイト数を返します。 入力値を解析できない場合、この関数は NULL を返します。

この関数の逆演算は formatReadableSize と formatReadableDecimalSize です。

構文

parseReadableSizeOrNull(x)

引数

• x — ISO/IEC 80000-13 または 10 進バイト単位で表された、人が読みやすい形式のサイズ。String

戻り値

バイト数を返します。最も近い整数に切り上げられ、入力を解析できない場合は NULL を返します。Nullable(UInt64)

例

使用例

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

​

parseReadableSizeOrZero

導入バージョン: v24.6.0

バイトサイズを表す文字列を受け取り、単位として B、KiB、KB、MiB、MB など (つまり ISO/IEC 80000-13 または 10 進バイト単位) を含む場合、この関数は対応するバイト数を返します。 この関数が入力値を解析できない場合は、0 を返します。

この関数の逆関数にあたるのは formatReadableSize と formatReadableDecimalSize です。

構文

parseReadableSizeOrZero(x)

引数

• x — ISO/IEC 80000-13 または 10 進のバイト単位による、人間が読みやすいサイズ。String

戻り値

最も近い整数に切り上げたバイト数を返します。入力をパースできない場合は 0 を返します。UInt64

例

使用例

Query

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

Response

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

​

parseTimeDelta

導入バージョン: v22.7.0

数値の並びの後に時間単位に類する文字列が続く値を解析します。

time delta 文字列では、次の時間単位指定を使用できます。

• years, year, yr, y
• months, month, mo
• weeks, week, w
• days, day, d
• hours, hour, hr, h
• minutes, minute, min, m
• seconds, second, sec, s
• milliseconds, millisecond, millisec, ms
• microseconds, microsecond, microsec, μs, µs, us
• nanoseconds, nanosecond, nanosec, ns

複数の時間単位は、区切り文字 (空白、;、-、+、,、:) を使って組み合わせることができます。

年と月の長さは概算です。1 年は 365 日、1 か月は 30.5 日として扱います。

構文

parseTimeDelta(timestr)

引数

• timestr — 数字の並びに、時間の単位を表す文字列が続く値。String

戻り値

秒数を表す値。Float64

例

使用例

Query

SELECT parseTimeDelta('11s+22min')

Response

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

複合時間単位

Query

SELECT parseTimeDelta('1yr2mo')

Response

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

​

partitionId

導入バージョン: v21.4.0

パーティション IDを計算します。

この関数は低速なため、大量の行に対しては呼び出さないでください。

構文

partitionId(column1[, column2, ...])

別名: partitionID

引数

• column1, column2, ... — パーティション ID を返す対象となるカラム。

戻り値

その行が属するパーティション ID を返します。 String

例

使用例

Query

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;

Response

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

​

pgGetUserById

導入バージョン: v26.8.0

PostgreSQL ワイヤプロトコルの互換性関数であり、pg_catalog.pg_get_userbyid に相当します。 PostgreSQL クライアント (たとえば、psql の \d コマンド) は、テーブルの所有者を表示するためにこの関数を使用します。 ClickHouse はテーブルの所有者を管理しないため、この関数は引数を無視し、現在のユーザー名を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

pgGetUserById(oid)

別名: pg_get_userbyid

引数

• oid — ロールのオブジェクト識別子。値は無視されます。UInt32

戻り値

現在のユーザー名を返します。String

例

使用例

Query

SELECT pg_get_userbyid(10)

Response

┌─pg_get_userbyid(10)─┐
│ default             │
└─────────────────────┘

​

pgTableIsVisible

導入バージョン: v26.8.0

PostgreSQL ワイヤプロトコルとの互換性関数で、pg_catalog.pg_table_is_visible に相当します。 PostgreSQL クライアント (たとえば psql の \d コマンド) は、検索パス内で可視のテーブルを絞り込むためにこの関数を使用します。 ClickHouse がエミュレートする pg_class ビューには、すべて可視である現在のデータベースのテーブルのみが含まれるため、この関数は常に 1 を返します。

構文

pgTableIsVisible(oid)

別名: pg_table_is_visible

引数

• oid — エミュレートされた pg_class ビューで公開されるテーブルのオブジェクト識別子。この値は無視されます。UInt32

戻り値

常に 1 を返します。UInt8

例

使用例

Query

SELECT pg_table_is_visible(0)

Response

┌─pg_table_is_visible(0)─┐
│                      1 │
└────────────────────────┘

​

queryID

導入バージョン: v21.9.0

現在のクエリの ID を返します。 クエリの他のパラメータは、system.query_log テーブルの query_id フィールドから取得できます。

initialQueryID 関数とは異なり、queryID は分片ごとに異なる結果を返す場合があります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

queryID()

別名: query_id

引数

• なし。

戻り値

現在のクエリIDを返します。 String

例

使用例

Query

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());

Response

┌─countDistinct(t)─┐
│                3 │
└──────────────────┘

​

リビジョン

導入バージョン: v22.7.0

現在の ClickHouseサーバー のリビジョン番号を返します。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

revision()

引数

• なし。

戻り値

現在のClickHouseサーバーのリビジョンを返します。UInt32

例

使用例

Query

SELECT revision()

Response

┌─revision()─┐
│      54485 │
└────────────┘

​

rowNumberInAllBlocks

導入バージョン: v1.1.0

処理される各行に対して一意の行番号を返します。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

rowNumberInAllBlocks()

引数

• なし。

戻り値

データブロック内の行番号を、0 から始まる序数で返します。UInt64

例

使用例

Query

-- The data is processed in blocks of two rows: rowNumberInBlock restarts from 0 in every block,
-- while rowNumberInAllBlocks keeps counting across them.
SELECT
    number,
    rowNumberInBlock(),
    rowNumberInAllBlocks()
FROM system.numbers
LIMIT 6
SETTINGS max_block_size = 2

Response

┌─number─┬─rowNumberInBlock()─┬─rowNumberInAllBlocks()─┐
│      0 │                  0 │                      0 │
│      1 │                  1 │                      1 │
│      2 │                  0 │                      2 │
│      3 │                  1 │                      3 │
│      4 │                  0 │                      4 │
│      5 │                  1 │                      5 │
└────────┴────────────────────┴────────────────────────┘

​

rowNumberInBlock

導入バージョン: v1.1.0

rowNumberInBlock は、処理対象の各ブロックについて、現在の行の番号を返します。

返される番号は、各ブロックごとに 0 から始まります。

この関数は非決定論的です。同じ引数に対して、異なる結果を返すことがあります。

構文

rowNumberInBlock()

引数

• なし。

戻り値

0 から始まるデータブロック内の行の序数を返します。UInt64

例

使用例

Query

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

Response

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
└────────────────────┘

​

runningAccumulate

導入バージョン: v1.1.0

データブロックの各行について、集約関数の状態を累積します。

状態は新しいデータブロックごとにリセットされます。 この挙動は誤りを招きやすいため、この関数は非推奨となっており、代わりにウィンドウ関数を使用することを推奨します。 この関数の使用を許可するには、設定allow_deprecated_error_prone_window_functionsを使用できます。

構文

runningAccumulate(agg_state[, grouping])

引数

• agg_state — 集約関数の状態。AggregateFunction
• grouping — 任意。グループ化キー。grouping の値が変わると、関数の状態はリセットされます。等価演算子が定義されている任意のサポート対象データ型を指定できます。Any

戻り値

各行の累積結果を返します。Any

例

initializeAggregation を使用した使用例

Query

SET allow_deprecated_error_prone_window_functions = 1;
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(5);

Response

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

​

runningConcurrency

導入バージョン: v21.3.0

同時実行されているイベント数を計算します。 各イベントには開始時刻と終了時刻があります。 開始時刻はイベントに含まれますが、終了時刻は含まれません。 開始時刻と終了時刻のカラムは、同じデータ型である必要があります。 この関数は、各イベントの開始時刻ごとに、アクティブな (同時実行中の) イベントの総数を計算します。

イベントは開始時刻の昇順で並んでいる必要があります。 この要件に違反すると、関数は例外をスローします。 各データブロックは個別に処理されます。 異なるデータブロックに属するイベントが重なっている場合、正しく処理できません。

代わりに ウィンドウ関数 を使用することを推奨します。

この関数は非決定論的です。同じ引数に対して異なる結果を返す場合があります。

構文

runningConcurrency(start, end)

引数

• start — イベントの開始時刻を表すカラム。Date または DateTime または DateTime64
• end — イベントの終了時刻を表すカラム。Date または DateTime または DateTime64

戻り値

各イベントの開始時点で同時に発生しているイベント数を返します。UInt32

例

使用例

Query

CREATE TABLE example_table (start Date, end Date) ENGINE = Memory;
INSERT INTO example_table VALUES ('2025-03-03', '2025-03-11'), ('2025-03-06', '2025-03-08'), ('2025-03-07', '2025-03-09'), ('2025-03-11', '2025-03-12');

SELECT start, runningConcurrency(start, end) FROM example_table;

Response

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              1 │
└────────────┴────────────────────────────────┘

​

runningDifference

導入バージョン: v1.1.0

データブロック内で連続する2つの行の値の差を計算します。 最初の行には 0 を返し、2 行目以降は直前の行との差を返します。

現在処理中のデータブロック内の差分しか返しません。 この挙動は誤りを招きやすいため、この関数は非推奨です。 代わりに ウィンドウ関数 を使用することを推奨します。

この関数の使用を許可するには、設定 allow_deprecated_error_prone_window_functions を使用できます。

この関数の結果は、対象となるデータブロックと、そのブロック内でのデータの順序に依存します。 runningDifference() の計算時の行の順序は、ユーザーに返される行の順序と異なる場合があります。 これを防ぐには、ORDER BY を含むサブクエリを作成し、その外側でこの関数を呼び出します。 ブロックサイズが結果に影響する点に注意してください。 runningDifference の内部状態は、新しいブロックごとにリセットされます。

構文

runningDifference(x)

引数

• x — 連続する値の差分を計算する対象のカラム。Any

戻り値

連続する値どうしの差分を返します。最初の行は 0 です。

例

使用例

Query

SET allow_deprecated_error_prone_window_functions = 1;

CREATE TABLE events
(
    EventID UInt32,
    EventDate Date,
    EventTime DateTime
)
ENGINE = Memory;

INSERT INTO events VALUES
    (1106, '2025-11-24', '2025-11-24 00:00:04'),
    (1107, '2025-11-24', '2025-11-24 00:00:05'),
    (1108, '2025-11-24', '2025-11-24 00:00:05'),
    (1109, '2025-11-24', '2025-11-24 00:00:09'),
    (1110, '2025-11-24', '2025-11-24 00:00:10');

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC, EventID ASC
    LIMIT 5
);

Response

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

ブロックサイズの影響の例

Query

SET allow_deprecated_error_prone_window_functions = 1;
SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;

Response

┌─number─┬─diff─┐
│      0 │    0 │
│  65409 │    0 │
└────────┴──────┘

​

runningDifferenceStartingWithFirstValue

導入バージョン: v1.1.0

データブロック内で連続する行の値の差を計算しますが、runningDifference とは異なり、最初の行については 0 ではなく実際の値を返します。

現在処理中のデータブロック内の差分しか返しません。 この挙動はエラーを招きやすいため、この関数は非推奨です。 代わりに ウィンドウ関数 を使用することを推奨します。

この関数の使用を許可するには、設定 allow_deprecated_error_prone_window_functions を使用できます。

構文

runningDifferenceStartingWithFirstValue(x)

引数

• x — 連続する値の差分を計算する対象のカラム。Any

戻り値

連続する値同士の差を返します。先頭の行については、その行の値を返します。Any

例

使用例

Query

SET allow_deprecated_error_prone_window_functions = 1;
SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

Response

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

​

serverUUID

導入バージョン: v20.1.0

server の初回起動時に生成される、ランダムで一意な UUID (v4) を返します。 この UUID は永続化されるため、2 回目、3 回目以降に server を起動しても、同じ UUID が返されます。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

serverUUID()

引数

• なし。

戻り値

サーバーのランダムなUUIDを返します。UUID

例

使用例

Query

SELECT serverUUID();

Response

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

​

shardCount

導入バージョン: v21.9.0

分散クエリにおける分片の総数を返します。 クエリが分散されていない場合は、定数値 0 が返されます。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

shardCount()

引数

• なし。

戻り値

分片の総数、または 0 を返します。UInt32

例

使用例

Query

-- See shardNum() example above which also demonstrates shardCount()
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

Response

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

​

shardNum

導入バージョン: v21.9.0

分散クエリでデータの一部を処理する分片の番号を返します。 番号は 1 から始まります。 クエリが分散クエリでない場合は、定数値 0 が返されます。

この関数は非決定論的です。同じ引数でも異なる結果を返すことがあります。

構文

shardNum()

引数

• なし。

戻り値

分片の索引、または定数 0 を返します。UInt32

例

使用例

Query

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;

Response

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          1 │            2 │
│     0 │          2 │            2 │
└───────┴────────────┴──────────────┘

​

showCertificate

導入バージョン: v22.6.0

設定されている場合は、現在のサーバーの Secure Sockets Layer (SSL) 証明書に関する情報を表示します。 サーバーに証明書がない場合は空のマップを返します。たとえば、証明書が ACME によってプロビジョニングされており、まだ発行されていない場合です。 接続の検証に OpenSSL 証明書を使用するように ClickHouse を設定する方法について詳しくは、TLS の設定 を参照してください。

この関数は非決定論的です。同じ引数に対して異なる結果を返す可能性があります。

構文

showCertificate()

引数

• なし。

戻り値

設定された SSL 証明書に関連するキー・バリューのペアを格納したマップを返します。Map(String, String)

例

使用例

Query

SELECT showCertificate() FORMAT LineAsString;

Response

{'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'}

​

sleep

導入バージョン: v1.1.0

指定した秒数だけクエリの実行を一時停止します。 この関数は主に、テストやデバッグのために使用されます。

sleep() 関数は、クエリのパフォーマンスやシステムの応答性に悪影響を及ぼす可能性があるため、通常、本番環境では使用すべきではありません。 ただし、次のような場面では有用です。

1. テスト: ClickHouse のテストやベンチマークを行う際に、遅延をシミュレートしたり一時停止を挟んだりして、特定の条件下でシステムがどのように動作するかを観察したい場合があります。
2. デバッグ: 特定の時点におけるシステムの状態やクエリの実行状況を確認する必要がある場合は、sleep() を使って一時停止を入れることで、関連情報を調査または収集できます。
3. シミュレーション: ネットワークレイテンシーや外部システムへの依存関係など、遅延や一時停止が発生する実際の状況をシミュレートしたい場合があります。

sleep() 関数は、ClickHouse システム全体のパフォーマンスや応答性に影響を及ぼすおそれがあるため、本当に必要な場合にのみ慎重に使用することが重要です。

セキュリティ上の理由により、この関数を実行できるのは、デフォルトのユーザープロファイル (allow_sleep が有効な場合) のみです。

構文

sleep(seconds)

引数

• seconds — クエリの実行を最大 3 秒まで一時停止する秒数です。小数秒を指定するには、浮動小数点値も使用できます。const UInt* または const Float*

戻り値

0 を返します。UInt8

例

使用例

Query

-- This query will pause for 2 seconds before completing.
-- During this time, no results will be returned, and the query will appear to be hanging or unresponsive.
SELECT sleep(2);

Response

┌─sleep(2)─┐
│        0 │
└──────────┘

​

sleepEachRow

導入バージョン: v1.1.0

結果セットの各行ごとに、指定した秒数だけクエリの実行を一時停止します。

sleepEachRow() 関数は、sleep() 関数と同様に、主にテストやデバッグのために使用されます。 この関数を使うと、各行の処理ごとに遅延や一時停止を発生させることができ、次のような場面で役立ちます。

1. テスト: 特定の条件下で ClickHouse の性能をテストまたはベンチマークする際に、sleepEachRow() を使って、処理される各行ごとに遅延や一時停止を発生させることができます。
2. デバッグ: 処理される各行について、システムの状態やクエリの実行状況を確認する必要がある場合は、sleepEachRow() で一時停止を入れることで、関連情報を調査したり収集したりできます。
3. シミュレーション: 場合によっては、外部システムやネットワーク遅延を扱うケースのように、処理される各行ごとに遅延や一時停止が発生する実運用に近い状況をシミュレートしたいことがあります。

sleep() 関数と同様に、sleepEachRow() は必要な場合にのみ慎重に使用することが重要です。特に大きな結果セットを扱う場合、ClickHouse システム全体の性能や応答性に大きな影響を与える可能性があります。

構文

sleepEachRow(seconds)

引数

• seconds — 結果セットの各行に対して、クエリの実行を最大 3 秒まで一時停止する秒数です。小数秒を指定するには浮動小数点値を使用できます。const UInt* または const Float*

戻り値

各行に 0 を返します。UInt8

例

使用例

Query

-- The output will be delayed, with a 0.5-second pause between each row.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

Response

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

​

structureToCapnProtoSchema

導入バージョン: v23.8.0

ClickHouseのテーブル構造をCapnProtoフォーマットのスキーマに変換する関数

構文

structureToCapnProtoSchema(table_structure, message)

引数

• なし。

戻り値

例

ランダム

Query

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

Response

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

​

structureToProtobufSchema

導入バージョン: v23.8.0

ClickHouseのテーブル構造をProtobufフォーマットのスキーマに変換します。

この関数は、ClickHouseのテーブル構造定義を受け取り、proto3構文の Protocol Buffers (Protobuf) スキーマ定義に変換します。これは、データ交換用にClickHouseの テーブル構造に対応したProtobufスキーマを生成する際に役立ちます。

構文

structureToProtobufSchema(structure, message_name)

引数

• structure — 文字列で指定する ClickHouse テーブルの構造定義です (例: ‘column1 Type1, column2 Type2’) 。String
• message_name — 生成されるスキーマ内の Protobuf メッセージ型の名前です。String

戻り値

入力された ClickHouse テーブル構造に対応する、proto3 構文の Protobuf スキーマ定義を返します。String

例

ClickHouse テーブル構造を Protobuf スキーマに変換する

Query

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

Response

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

​

tcpPort

導入バージョン: v20.12.0

サーバーが待ち受けているネイティブインターフェイスのTCPポート番号を返します。 分散テーブルに対して実行された場合、この関数は各分片に対応する値を持つ通常のカラムを生成します。 それ以外の場合は、定数値を返します。

この関数は非決定論的です。同じ引数に対しても異なる結果を返すことがあります。

構文

tcpPort()

引数

• ありません。

戻り値

TCPポート番号を返します。UInt16

例

使用例

Query

SELECT tcpPort()

Response

┌─tcpPort()─┐
│      9000 │
└───────────┘

​

throwIf

導入バージョン: v1.1.0

引数 x が true の場合、例外をスローします。 error_code 引数を使用するには、設定パラメータ allow_custom_error_code_in_throw を有効にする必要があります。

構文

throwIf(x[, message[, error_code]])

引数

• x — 確認する条件。Any
• message — 任意。カスタムエラーメッセージ。const String
• error_code — 任意。カスタムエラーコード。const Int8/16/32

戻り値

条件が false の場合は 0 を返し、条件が true の場合は例外がスローされます。UInt8

例

使用例

Query

SELECT throwIf(number = 3, 'Too many') FROM numbers(10);

Response

Received exception:
Code: 395. DB::Exception: Too many. (FUNCTION_THROW_IF_VALUE_IS_NON_ZERO)

​

toColumnTypeName

導入バージョン: v1.1.0

指定された値のデータ型の内部名を返します。 関数 toTypeName とは異なり、返されるデータ型には Const や LowCardinality などの内部ラッパーのカラムが含まれる場合があります。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

toColumnTypeName(value)

引数

• value — 内部データ型を返す対象となる値。Any

戻り値

値を表現するために使用される内部データ型を返します。String

例

使用例

Query

SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));

Response

┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

​

toTypeName

導入バージョン: v1.1.0

渡された引数の型名を返します。 NULL が渡された場合、この関数は型 Nullable(Nothing) を返します。これは ClickHouse の内部的な NULL 表現に対応します。

構文

toTypeName(x)

引数

• x — 任意の型の値。Any

戻り値

入力値の型名を返します。String

例

使用例

Query

SELECT toTypeName(123)

Response

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

​

tokenizeQuery

導入バージョン: v26.5.0

ClickHouse SQL のクエリ文字列をトークン化し、トークンの配列を返します。 各トークンは、開始位置 (バイト単位) 、終了位置、およびトークンの型を持つ名前付きタプルです。

構文

tokenizeQuery(query)

引数

• query — ClickHouse SQLクエリの文字列。String。

戻り値

クエリのトークンを表す、名前付きタプル (begin UInt64, end UInt64, type Enum8(...)) の配列。Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

例

シンプル

Query

SELECT tokenizeQuery('SELECT 1')

Response

[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]

​

transactionID

導入バージョン: v22.6.0

トランザクションの ID を返します。

この関数は実験的機能セットの一部です。 実験的なトランザクションサポートを有効にするには、次の設定を 設定 に追加してください。

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

詳しくは、Transactional (ACID) support のページを参照してください。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

transactionID()

引数

• なし。

戻り値

start_csn、local_tid、host_id、session_node_version で構成されるタプルを返します。

• start_csn: グローバルな連番。このトランザクションの開始時点で確認されていた最新のコミットタイムスタンプです。
• local_tid: ローカルな連番。特定の start_csn 内で、このホストによって開始された各トランザクションごとに一意です。
• host_id: このトランザクションを開始したホストの UUID。
• session_node_version: トランザクション開始時点におけるホストの session znode のバージョン。これにより、ピアはレプリカ間で終了済みセッションの TID を検出できます。 Tuple(UInt64, UInt64, UUID, Int64)

例

使用例

Query

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

Response

┌─transactionID()──────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b',1) │
└──────────────────────────────────────────────────┘

​

transactionLatestSnapshot

導入バージョン: v22.6.0

読み取りに利用可能なトランザクションの最新のスナップショット (Commit Sequence Number) を返します。

この関数は実験的機能セットの一部です。実験的なトランザクションサポートを有効にするには、設定に次の項目を追加してください。

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

詳細については、Transactional (ACID) supportのページを参照してください。

構文

transactionLatestSnapshot()

引数

• なし。

戻り値

トランザクションの最新スナップショット (CSN) を返します。UInt64

例

使用例

Query

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

Response

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

​

transactionOldestSnapshot

導入バージョン: v22.6.0

実行中のトランザクションから参照可能な、最も古いスナップショット (Commit Sequence Number) を返します。

この関数は実験的機能セットの一部です。以下の設定を構成に追加して、実験的なトランザクションサポートを有効にしてください。

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

詳細については、Transactional (ACID) support のページを参照してください。

構文

transactionOldestSnapshot()

引数

• なし。

戻り値

トランザクションの最も古いスナップショット (CSN) を返します。UInt64

例

使用例

Query

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

Response

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

​

transform

導入バージョン: v1.1.0

明示的に定義された要素間のマッピングに基づいて、値を変換します。

この関数には 2 つのバリエーションがあります。

• transform(x, array_from, array_to, default) - マッピング用の配列を使って x を変換し、一致しない要素にはデフォルト値を返します
• transform(x, array_from, array_to) - 同じ変換を行いますが、一致する要素が見つからない場合は元の x を返します

この関数は array_from 内で x を検索し、同じ索引の array_to にある対応する要素を返します。 x が array_from 内で見つからない場合は、default の値 (4 パラメータ版) または元の x (3 パラメータ版) を返します。 array_from に一致する要素が複数ある場合は、最初の一致に対応する要素を返します。

要件:

• array_from と array_to は同じ数の要素を持っている必要があります
• 4 パラメータ版: transform(T, Array(T), Array(U), U) -> U - ここで T と U には、互換性のある異なる型を使用できます
• 3 パラメータ版: transform(T, Array(T), Array(T)) -> T - ここですべての型は同じである必要があります

構文

transform(x, array_from, array_to[, default])

引数

• x — 変換対象の値。(U)Int* または Decimal または Float* または String または Date または DateTime
• array_from — 一致する値を検索する対象の定数配列。Array((U)Int*) または Array(Decimal) または Array(Float*) または Array(String) または Array(Date) または Array(DateTime)
• array_to — array_from 内で対応する一致が見つかった場合に返される値の定数配列。Array((U)Int*) または Array(Decimal) または Array(Float*) または Array(String) または Array(Date) または Array(DateTime)
• default — 任意。x が array_from 内に見つからない場合に返す値。省略した場合は、x をそのまま返します。(U)Int* または Decimal または Float* または String または Date または DateTime

戻り値

x が array_from の要素に一致する場合は array_to の対応する値を返し、それ以外の場合は default (指定されている場合) または x (default が指定されていない場合) を返します。Any

例

transform(T, Array(T), Array(U), U) -> U

Query

CREATE TABLE hits (SearchEngineID UInt8, Referer String) ENGINE = Memory;

INSERT INTO hits VALUES
    (2, 'http://yandex.ru/search'),
    (2, 'http://yandex.ru/news'),
    (2, 'http://mail.yandex.ru/'),
    (3, 'http://google.ru/search'),
    (4, 'http://duckduckgo.com/'),
    (0, 'http://vkontakte.ru/feed'),
    (0, '');

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC, title

Response

┌─title──┬─c─┐
│ Yandex │ 3 │
│ Google │ 1 │
│ Other  │ 1 │
└────────┴───┘

transform(T, Array(T), Array(T)) -> T

Query

-- Without a default, a domain that is not listed is returned unchanged.
SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM hits
GROUP BY domain(Referer)
ORDER BY count() DESC, s
LIMIT 10

Response

┌─s──────────────┬─c─┐
│ www.yandex     │ 2 │
│                │ 1 │
│ duckduckgo.com │ 1 │
│ example.com    │ 1 │
│ mail.yandex.ru │ 1 │
│ vk.com         │ 1 │
└────────────────┴───┘

​

uniqThetaIntersect

導入バージョン: v22.9.0

2 つの uniqThetaSketch オブジェクト に対して積集合の計算 (集合演算 ∩) を行い、その結果として新しい uniqThetaSketch を返します。

構文

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

引数

• uniqThetaSketch — uniqThetaSketch オブジェクト。Tuple または Array または Date または DateTime または String または (U)Int* または Float* または Decimal

戻り値

積集合の結果を含む新しい uniqThetaSketch。 UInt64

例

使用例

Query

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

​

uniqThetaNot

導入バージョン: v22.9.0

2 つの uniqThetaSketch オブジェクトに対して a_not_b 計算 (集合演算 ×) を実行し、その結果として新しい uniqThetaSketch を返します。

構文

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

引数

• uniqThetaSketch — uniqThetaSketch オブジェクト。Tuple または Array または Date または DateTime または String または (U)Int* または Float* または Decimal

戻り値

a_not_b の結果を含む、新しい uniqThetaSketch を返します。UInt64

例

使用例

Query

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

Response

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

​

uniqThetaUnion

導入バージョン: v22.9.0

2 つの uniqThetaSketch オブジェクトに対してユニオン計算 (集合演算 ∪) を行い、結果として新しい uniqThetaSketch を返します。

構文

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

引数

• uniqThetaSketch — uniqThetaSketch オブジェクト。Tuple または Array または Date または DateTime または String または (U)Int* または Float* または Decimal

戻り値

ユニオン結果を含む新しい uniqThetaSketch を返します。UInt64

例

使用例

Query

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

Response

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

​

稼働時間

導入バージョン: v1.1.0

サーバーの稼働時間を秒単位で返します。 分散テーブルに対して実行すると、この関数は各分片に対応する値を持つ通常のカラムを生成します。 それ以外の場合は、定数値を生成します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

uptime()

引数

• ありません。

戻り値

serverの稼働時間を秒単位で返します。 UInt32

例

使用例

Query

SELECT uptime() AS Uptime

Response

┌─Uptime─┐
│  55867 │
└────────┘

​

variantElement

導入バージョン: v25.2.0

Variant カラムから、指定した型のカラムを抽出します。

構文

variantElement(variant, type_name[, default_value])

引数

• variant — Variant カラム。 Variant
• type_name — 抽出する Variant 型の名前。 String
• default_value — variant に指定した型の値がない場合に使用されるデフォルト値。任意の型を指定できます。省略可能です。 Any

戻り値

Variant カラムから指定した Variant 型の値を抽出したカラムを返します。 Any

例

使用例

Query

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;

Response

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

​

variantType

導入バージョン: v24.2.0

Variant カラムの各行について、Variant 型名を返します。行に NULL が含まれている場合、その行については ‘None’ を返します。

構文

variantType(variant)

引数

• variant — Variant カラム。Variant

戻り値

各行の Variant 型名を格納した Enum カラムを返します。Enum

例

使用例

Query

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;

Response

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

​

version

導入バージョン: v1.1.0

ClickHouse の現在のバージョンを、major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release 形式の文字列として返します。 分散テーブル上で実行された場合、この関数は各分片に対応する値を持つ通常のカラムを生成します。 それ以外の場合は、定数値を返します。

この関数は非決定論的です。同じ引数に対して異なる結果を返すことがあります。

構文

version()

引数

• ありません。

戻り値

現在の ClickHouse のバージョンを返します。String

例

使用例

Query

SELECT version()

Response

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

​

visibleWidth

導入バージョン: v1.1.0

値をテキスト形式 (タブ区切り) でコンソールに出力する際の、おおよその幅を計算します。 この関数は、システムが Pretty フォーマットを実装するために使用されます。 NULL は、Pretty フォーマットでは NULL に対応する文字列として表現されます。

構文

visibleWidth(x)

引数

• x — 任意のデータ型の値。Any

戻り値

テキストフォーマットで表示した場合のおおよその幅を返します。UInt64

例

NULL の表示幅を計算

Query

SELECT visibleWidth(NULL)

Response

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

​

zookeeperSessionUptime

導入バージョン: v21.11.0

現在のZooKeeperセッションの稼働時間を秒単位で返します。

この関数は非決定論的なため、同じ引数でも異なる結果を返すことがあります。

構文

zookeeperSessionUptime()

引数

• なし。

戻り値

現在の ZooKeeper セッションの稼働時間を秒単位で返します。 UInt32

例

使用例

Query

SELECT zookeeperSessionUptime();

Response

┌─zookeeperSessionUptime()─┐
│                        3 │
└──────────────────────────┘