その他の関数

注記

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

FQDN

導入バージョン: v20.1

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

構文

FQDN()

別名: fullHostName

引数

なし。

戻り値

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

例

使用例

SELECT fqdn()

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

MACNumToString

導入: v1.1

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

構文

MACNumToString(num)

引数

num — UInt64 型の数値。UInt64

戻り値

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

例

使用例

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:00:11:22:33:44 │
└───────────────────┘

MACStringToNum

導入バージョン: v1.1

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

構文

MACStringToNum(s)

引数

s — MAC アドレスを表す文字列。String

戻り値

UInt64 の数値を返します。UInt64

例

使用例

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

1108152157446

MACStringToOUI

導入バージョン: v1.1

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

構文

MACStringToOUI(s)

引数

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

返り値

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

例

使用例

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

authenticatedUser

導入バージョン: v25.11

セッションのユーザーが EXECUTE AS コマンドで切り替えられている場合、この関数は認証およびセッションの確立時に使用された元のユーザー名を返します。エイリアス: authUser()

構文

authenticatedUser()

別名: authUser

引数

なし。

戻り値

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

例

使用例

EXECUTE as u1;
            SELECT currentUser(), authenticatedUser();

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

bar

導入バージョン: v1.1

棒グラフを作成します。幅が (x - min) に比例し、x = max のときに width 文字となる帯を描画します。帯は文字幅の 1/8 単位の精度で描画されます。

構文

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

例

使用例

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

┌──h─┬──────c─┬─bar────────────────┐
│  0 │ 292907 │ █████████▋         │
│  1 │ 180563 │ ██████             │
│  2 │ 114861 │ ███▋               │
│  3 │  85069 │ ██▋                │
│  4 │  68543 │ ██▎                │
│  5 │  78116 │ ██▌                │
│  6 │ 113474 │ ███▋               │
│  7 │ 170678 │ █████▋             │
│  8 │ 278380 │ █████████▎         │
│  9 │ 391053 │ █████████████      │
│ 10 │ 457681 │ ███████████████▎   │
│ 11 │ 493667 │ ████████████████▍  │
│ 12 │ 509641 │ ████████████████▊  │
│ 13 │ 522947 │ █████████████████▍ │
│ 14 │ 539954 │ █████████████████▊ │
│ 15 │ 528460 │ █████████████████▌ │
│ 16 │ 539201 │ █████████████████▊ │
│ 17 │ 523539 │ █████████████████▍ │
│ 18 │ 506467 │ ████████████████▊  │
│ 19 │ 520915 │ █████████████████▎ │
│ 20 │ 521665 │ █████████████████▍ │
│ 21 │ 542078 │ ██████████████████ │
│ 22 │ 493642 │ ████████████████▍  │
│ 23 │ 400397 │ █████████████▎     │
└────┴────────┴────────────────────┘

blockNumber

導入バージョン: v1.1

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

構文

blockNumber()

引数

なし。

戻り値

行が格納されているデータブロックのシーケンス番号。UInt64

例

基本的な使用例

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

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

blockSerializedSize

導入バージョン: v20.3

ディスク上に格納された値のブロックの非圧縮時のサイズ（バイト数）を返します。

構文

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

引数

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

返される値

圧縮を行わずに値のブロックがディスクに書き込まれるバイト数を返します。UInt64

例

使用例

SELECT blockSerializedSize(maxState(1)) AS x;

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

blockSize

導入バージョン: v1.1

ClickHouse では、クエリは blocks（chunk）ごとに処理されます。この関数は、呼び出されたブロックのサイズ（行数）を返します。

構文

blockSize()

引数

なし。

戻り値

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

例

使用例

SELECT blockSize()
FROM system.numbers LIMIT 5

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

buildId

導入バージョン: v20.5

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

構文

buildId()

引数

なし。

戻り値

ビルド ID を返します。String

例

使用例

SELECT buildId()

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

byteSize

導入バージョン: v21.1

引数がメモリ上で非圧縮状態のときに占めるバイトサイズを推定して返します。 String 引数に対しては、文字列の長さ + 8（長さ情報）を返します。複数の引数が指定された場合、各引数のバイトサイズを合算します。

構文

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

引数

arg1[, arg2, ...] — 非圧縮時のバイトサイズを推定するための任意のデータ型の値。Any

戻り値

引数のメモリ上でのバイトサイズの推定値を返します。UInt64

例

使用例

SELECT byteSize('string')

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

複数の引数

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

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

catboostEvaluate

導入バージョン: v22.9

外部の catboost モデルを評価します。CatBoost は、Yandex によって機械学習向けに開発されたオープンソースの勾配ブースティングライブラリです。 catboost モデルファイルへのパスと、モデルの引数（特徴量）を受け取ります。

前提条件

catboost 評価用ライブラリをビルドする

catboost モデルを評価する前に、libcatboostmodel.<so|dylib> ライブラリを利用可能な状態にしておく必要があります。コンパイル方法については CatBoost documentation を参照してください。

次に、ClickHouse の設定で libcatboostmodel.<so|dylib> へのパスを指定します。

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

セキュリティおよびアイソレーションの観点から、モデルの評価はサーバープロセス内ではなく、clickhouse-library-bridge プロセス内で実行されます。 catboostEvaluate() を最初に実行するとき、まだ稼働していなければサーバーは clickhouse-library-bridge プロセスを起動します。両方のプロセスは HTTP インターフェースを使って通信します。デフォルトではポート 9012 が使用されます。ポート 9012 がすでに別のサービスに割り当てられている場合などには、次のようにして別のポートを指定できます。

<library_bridge>
    <port>9019</port>
</library_bridge>

libcatboost を使用して catboost モデルを学習する

学習用データセットから catboost モデルを学習する方法については、Training and applying models を参照してください。

構文

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

引数

path_to_model — CatBoost モデルへのパス。const String
feature — 1つ以上のモデル特徴量または引数。Float*

戻り値

モデルの評価結果を返します。Float64

例

catboostEvaluate

SELECT catboostEvaluate('/root/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

colorOKLABToSRGB

導入バージョン: v26.2

OKLab 知覚色空間で表現された色を sRGB 色空間の色に変換します。

入力の色は OKLab 色空間で指定されます。入力値が典型的な OKLab の範囲外である場合、結果は実装依存です。

OKLab は次の 3 つの成分を使用します:

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

a および b 成分は理論上は無限大の範囲を取り得ますが、実際には -0.4 から 0.4 の間です。 OKLab は、計算コストを低く抑えつつ知覚的な一様性を実現するように設計されています。

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

OKLab から線形 sRGB への変換。 2) 線形 sRGB からガンマ符号化された sRGB への変換。

省略可能な gamma 引数は、線形 sRGB からガンマ符号化された RGB 値に変換する際に使用される指数を指定します。指定されない場合は、colorSRGBToOKLAB との一貫性のために既定の gamma 値が使用されます。

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

構文

colorOKLABToSRGB(tuple [, gamma])

引数

tuple — 数値 L、a、b から成る 3 要素のタプルで、L は [0...1] の範囲。Tuple(Float64, Float64, Float64)
gamma — 省略可能。各チャンネル x に対して (x ^ (1 / gamma)) * 255 を適用して線形 sRGB を sRGB に戻す際に使用される指数。デフォルト値は 2.2。Float64

戻り値

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

使用例

OKLAB を sRGB (Float) に変換

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

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

OKLAB を sRGB (UInt8) に変換する

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

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

colorOKLCHToSRGB

導入バージョン: v25.7

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

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

注記

OKLCH は、OKLab 色空間の円柱座標バージョンです。 3 つの成分は、L（明度、範囲 [0...1]）、C（彩度、>= 0）、H（色相、度単位で [0...360]）です。 OKLab/OKLCH は、計算コストを低く抑えつつ、知覚的均一性を実現するよう設計されています。

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

OKLCH から OKLab への変換 2) OKLab から Linear sRGB への変換 3) Linear sRGB から sRGB への変換

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

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

構文

colorOKLCHToSRGB(tuple [, gamma])

引数

tuple — 数値 L、C、H からなる 3 つ組のタプル。L は [0...1] の範囲、C >= 0、H は [0...360] の範囲。Tuple(Float64, Float64, Float64)
gamma — 省略可能。線形 sRGB を、各チャンネル x に対して (x ^ (1 / gamma)) * 255 を適用することで sRGB に戻す際に使用される指数。既定値は 2.2。Float64

返される値

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

例

OKLCH を sRGB に変換する

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

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

OKLCH を sRGB (UInt8) に変換する

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

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

colorSRGBToOKLAB

導入バージョン: v26.2

sRGB カラースペースで符号化された色を、知覚的に一様な OKLAB カラースペースに変換します。

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

注記

OKLAB は知覚的に一様なカラースペースです。その 3 つの座標は、L（明度、範囲 [0...1]）、a (Green-Red axis) および b (Blue-Yellow axis) です。 OKLab は、計算コストを抑えつつ知覚的な一様性を維持するように設計されています。

変換は 2 段階で構成されます:

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 に変換

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

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

colorSRGBToOKLCH

導入バージョン: v25.7

sRGB カラースペースでエンコードされた色を、知覚的に一様な OKLCH カラースペースに変換します。

いずれかの入力チャネルが [0...255] の範囲外、またはガンマ値が正の値でない場合、その挙動は実装依存です。

注記

OKLCH は OKLab カラースペースの円筒座標系バージョンです。 3 つの座標は L（[0...1] の範囲の明度）、C（彩度 >= 0）、H（[0...360] の範囲の度数で表される色相）です。 OKLab/OKLCH は、計算コストを低く抑えつつ知覚的な一様性を実現するよう設計されています。

変換は次の 3 段階で構成されます:

sRGB から Linear sRGB への変換 2) Linear sRGB から OKLab への変換 3) OKLab から OKLCH への変換

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

構文

colorSRGBToOKLCH(tuple[, gamma])

引数

tuple — 範囲 [0...255] の R, G, B 3 要素のタプル。Tuple(UInt8, UInt8, UInt8)
gamma — 省略可能。各チャネル x に対して (x / 255)^gamma を適用して sRGB を線形化する際に使用される指数。デフォルトは 2.2。Float64

戻り値

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

例

sRGB を OKLCH に変換

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

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

connectionId

導入バージョン: v21.3

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

構文

connectionId()

引数

なし。

戻り値

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

例

使用例

SELECT connectionId();

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

countDigits

導入バージョン: v20.8

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

注記

この関数は 10 進数値のスケールを考慮します。つまり、内部の整数型（(value * scale)）に対して結果を計算します。

例えば:

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

ヒント

Decimal64 の 10 進数のオーバーフローは countDigits(x) > 18 で確認できますが、 isDecimalOverflow よりも低速です。

構文

countDigits(x)

引数

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

戻り値

x を表すために必要な桁数を返します。UInt8

例

使用例

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

┌─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

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

SET 文も参照してください。

構文

currentDatabase()

別名: current_database, SCHEMA, DATABASE

引数

なし。

戻り値

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

例

使用例

SELECT currentDatabase()

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

currentProfiles

導入バージョン: v21.9

現在のユーザーに対して有効な設定プロファイルを配列で返します。

構文

currentProfiles()

引数

なし。

戻り値

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

例

使用例

SELECT currentProfiles();

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

currentQueryID

導入バージョン: v25.2

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

構文

currentQueryID()

別名: current_query_id

引数

なし。

戻り値

例

SELECT currentQueryID();

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

currentRoles

導入バージョン: v21.9

現在のユーザーに割り当てられているロールを配列として返します。

構文

currentRoles()

引数

なし。

戻り値

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

例

使用例

SELECT currentRoles();

┌─currentRoles()─────────────────────────────────┐
│ ['sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

currentSchemas

導入バージョン: v23.7

関数 currentDatabase と同様ですが、

無視される boolean 型の引数を受け取り、
データベース名を単一要素の配列として返します。

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

SET 文も参照してください。

構文

currentSchemas(bool)

エイリアス: current_schemas

引数

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

戻り値

現在のデータベース名のみを含む 1 要素の配列を返します。Array(String)

例

使用例

SELECT currentSchemas(true)

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

currentUser

導入バージョン: v20.1

現在のユーザーの名前を返します。分散クエリの場合は、そのクエリを実行したユーザーの名前を返します。

構文

currentUser()

別名: current_user, user

引数

なし

返される値

現在のユーザー名を返します。そうでない場合は、クエリを開始したユーザーのログイン名を返します。String

例

使用例

SELECT currentUser()

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

defaultProfiles

導入: v21.9

現在のユーザーに対して有効なデフォルト設定プロファイル名の配列を返します。

構文

defaultProfiles()

引数

なし。

戻り値

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

例

使用例

SELECT defaultProfiles();

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

defaultRoles

導入バージョン: v21.9

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

構文

defaultRoles()

引数

なし。

戻り値

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

例

使用例

SELECT defaultRoles();

┌─defaultRoles()─────────────────────────────────┐
│ ['sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────┘

defaultValueOfArgumentType

導入バージョン: v1.1

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

構文

defaultValueOfArgumentType(expression)

引数

expression — 任意の型の値、または任意の型の値を結果とする式。Any

戻り値

数値に対しては 0、文字列に対しては空文字列、Nullable 型に対しては NULL を返します。UInt8、String、または NULL

例

使用例

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

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

Nullable の例

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

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

defaultValueOfTypeName

導入バージョン: v1.1

指定された型名に対応するデフォルト値を返します。

構文

defaultValueOfTypeName(type)

引数

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

返される値

指定された型名に対応するデフォルト値を返します。数値型の場合は 0、文字列型の場合は空文字列、Nullable UInt8 または String の場合は NULL、型が NULL の場合も NULL を返します。

例

使用例

SELECT defaultValueOfTypeName('Int8');

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

Nullable の例

SELECT defaultValueOfTypeName('Nullable(Int8)');

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

displayName

導入バージョン: v22.11

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

構文

displayName()

引数

なし。

戻り値

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

例

使用例

SELECT displayName();

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

dumpColumnStructure

導入バージョン: v1.1

カラムの内部構造およびデータ型に関する詳細な情報を出力します。

構文

dumpColumnStructure(x)

引数

x — 説明を取得する対象となる値。Any

戻り値

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

例

使用例

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

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

enabledProfiles

導入バージョン: v21.9

現在のユーザーに対して有効な設定プロファイル名の配列を返します。

構文

enabledProfiles()

引数

なし。

戻り値

現在のユーザーに対して有効になっている setting プロファイル名を要素とする配列を返します。Array(String)

例

使用例

SELECT enabledProfiles();

┌─enabledProfiles()─────────────────────────────────────────────────┐
│ ['default', 'readonly_user', 'web_analytics', 'batch_processing'] │
└───────────────────────────────────────────────────────────────────┘

enabledRoles

導入バージョン: v21.9

現在のユーザーに対して有効化されているロールを配列で返します。

構文

enabledRoles()

引数

なし。

戻り値

現在のユーザーに対して有効になっているロール名の配列を返します。Array(String)

例

使用例

SELECT enabledRoles();

┌─enabledRoles()─────────────────────────────────────────────────┐
│ ['general_data', 'sql-console-role:jane.smith@clickhouse.com'] │
└────────────────────────────────────────────────────────────────┘

errorCodeToName

導入バージョン: v20.12

数値の ClickHouse エラーコードに対応する名前（文字列表現）を返します。数値のエラーコードからエラー名へのマッピングはこちらにあります。

構文

errorCodeToName(error_code)

引数

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

戻り値

error_code の文字列表現を返します。String

例

使用例

SELECT errorCodeToName(252);

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

file

導入バージョン: v21.3

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

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

構文

file(path[, default])

引数

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

戻り値

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

例

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

INSERT INTO table SELECT file('a.txt'), file('b.txt');

filesystemAvailable

導入バージョン: v20.1

データベースの永続データを格納しているファイルシステム上の空き容量を返します。返される値は、オペレーティングシステム用に一部の領域が予約されているため、常にファイルシステム全体の空き容量（filesystemUnreserved）よりも小さくなります。

構文

filesystemAvailable([disk_name])

引数

disk_name — 省略可。空き容量を取得する対象のディスク名を指定します。省略時はデフォルトディスクが使用されます。String または FixedString

戻り値

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

例

使用例

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

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

filesystemCapacity

導入バージョン: v20.1

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

構文

filesystemCapacity([disk_name])

引数

disk_name — 省略可能。容量を取得するディスク名。省略した場合は既定のディスクが使用されます。String または FixedString

返される値

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

例

使用例

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

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

filesystemUnreserved

導入バージョン: v22.12

データベースの永続データを格納しているファイルシステム上の、合計空き領域を返します（以前は filesystemFree）。 filesystemAvailable も参照してください。

構文

filesystemUnreserved([disk_name])

引数

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

返り値

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

例

使用例

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

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

finalizeAggregation

導入バージョン: v1.1

集約状態を引数に取り、この関数は集約結果（または -State コンビネータを使用している場合は最終化された状態）を返します。

構文

finalizeAggregation(state)

引数

state — 集約の状態。AggregateFunction

戻り値

最終的な集約結果を返します。Any

例

使用例

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

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

initializeAggregation と組み合わせて使用する

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

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

flipCoordinates

導入バージョン: v25.10

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

Point の場合は、その x 座標と y 座標を入れ替えます。より複雑なジオメトリ（LineString、Polygon、MultiPolygon、Ring、MultiLineString）の場合は、各座標ペアに対して再帰的にこの変換を適用します。

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

構文

flipCoordinates(geometry)

引数

geometry — 変換対象のジオメトリ。サポートされる型: Point (Tuple(Float64, Float64)), Ring (Array(Point)), Polygon (Array(Ring)), MultiPolygon (Array(Polygon)), LineString (Array(Point)), MultiLineString (Array(LineString)), または Geometry (これらのいずれかの型を格納する Variant)。

戻り値

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

例

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2.0, 1.0)

ring

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

[(2.0, 1.0), (4.0, 3.0)]

多角形

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

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

geometry_wkt

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

(20, 10)

geometry_polygon_wkt

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

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

formatQuery

導入バージョン: v23.10

指定した SQL クエリを整形し、場合によっては複数行にしたものを返します。パースエラーが発生した場合は例外をスローします。 [example:multiline]

構文

formatQuery(query)

引数

query — フォーマットされる SQL クエリ。String

返される値

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

例

複数行

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

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

formatQueryOrNull

導入バージョン: v23.11

指定された SQL クエリを、必要に応じて複数行に整形した形式で返します。構文解析エラーが発生した場合は NULL を返します。 [example:multiline]

構文

formatQueryOrNull(query)

引数

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

戻り値

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

例

複数行

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

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

formatQuerySingleLine

導入バージョン: v23.10

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

構文

formatQuerySingleLine(query)

引数

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

戻り値

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

例

複数行

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

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

formatQuerySingleLineOrNull

導入バージョン: v23.11

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

構文

formatQuerySingleLineOrNull(query)

引数

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

戻り値

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

例

複数行

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

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

formatReadableDecimalSize

導入バージョン: v22.11

サイズ（バイト数）を指定すると、この関数は接尾辞（KB、MB など）付きの、読みやすい丸め済みサイズを文字列として返します。

この関数の逆の処理は parseReadableSize です。

構文

formatReadableDecimalSize(x)

引数

x — バイト単位のサイズ。UInt64

戻り値

単位の接尾辞が付いた、人間が読みやすいように丸めたサイズを文字列として返します。String

例

ファイルサイズの整形

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

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

formatReadableQuantity

導入バージョン: v20.10

この関数は数値を入力として受け取り、丸めた数値に接尾辞（千、百万、十億など）を付けた文字列を返します。

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

構文

formatReadableQuantity(x)

引数

x — フォーマットする数値。UInt64

戻り値

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

例

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

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

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

formatReadableSize

導入バージョン: v1.1

サイズ（バイト数）を指定すると、この関数は接尾辞（KiB、MiB など）付きの、人間が読みやすく四捨五入されたサイズを文字列として返します。

この関数の逆変換を行う関数は、parseReadableSize、parseReadableSizeOrZero、parseReadableSizeOrNull です。この関数は任意の数値型を入力として受け取りますが、内部的には入力値を Float64 にキャストします。非常に大きな値に対しては、結果が最適にならない場合があります。

構文

formatReadableSize(x)

エイリアス: FORMAT_BYTES

引数

x — バイト単位のサイズ。UInt64

戻り値

丸められた読みやすいサイズを、単位（接尾辞）付きの文字列として返します。String

例

ファイルサイズの整形

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

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

formatReadableTimeDelta

導入バージョン: v20.12

秒単位の時間間隔（デルタ）を指定すると、この関数はその時間差を年/月/日/時/分/秒/ミリ秒/マイクロ秒/ナノ秒を含む文字列として返します。

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

構文

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

引数

column — 時間差を表す数値カラム。Float64
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

例

使用例

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

┌────elapsed─┬─time_delta─────────────────────────────────────────────────────┐
│        100 │ 1 minute and 40 seconds                                        │
│      12345 │ 3 hours, 25 minutes and 45 seconds                             │
│  432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds│
└────────────┴────────────────────────────────────────────────────────────────┘

最大単位付き

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

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

fuzzQuery

導入バージョン: v26.2

指定されたクエリ文字列をパースし、AST に対してランダムな変異（ファジング）を適用します。ファジング後のクエリを文字列として返します。非決定的であり、呼び出すたびに異なる結果が返される可能性があります。allow_fuzz_query_functions = 1 が必要です。

構文

fuzzQuery(query)

引数

query — ファジングされる SQL クエリ。String

戻り値

ファジングされたクエリ文字列 String

例

基本的な例

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

generateRandomStructure

導入: v23.5

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

例

使用例

SELECT generateRandomStructure()

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

指定したカラム数

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

シードを指定した場合

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8('c2V0' = 0, 'c2V1' = 1, 'c2V2' = 2, 'c2V3' = 3), c3 LowCardinality(Nullable(FixedString(30))), c4 Int16, c5 Enum8('c5V0' = 0, 'c5V1' = 1, 'c5V2' = 2, 'c5V3' = 3), c6 Nullable(UInt8), c7 String, c8 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(70)))

generateSerialID

導入バージョン: v25.1

直前のカウンター値から始まる連番を生成して返します。この関数は文字列引数（シリーズ識別子）と、任意の開始値を取ります。サーバーは Keeper が有効になるように構成されている必要があります。シリーズは Keeper ノード内のパス配下に保存され、このパスはサーバー設定の series_keeper_path で構成できます。

構文

generateSerialID(series_identifier[, start_value])

引数

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

戻り値

前回のカウンタ値から開始する連番を返します。UInt64

例

最初の呼び出し

SELECT generateSerialID('id1')

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

2回目の呼び出し

SELECT generateSerialID('id1')

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

カラムとしての呼び出し

SELECT *, generateSerialID('id1') FROM test_table

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

開始値付き

SELECT generateSerialID('id2', 100)

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

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

SELECT generateSerialID('id2', 100)

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

getClientHTTPHeader

導入バージョン: v24.5

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

注記

allow_get_client_http_header の設定が必須

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

この関数では HTTP ヘッダーは大文字と小文字が区別されます。分散クエリのコンテキストでこの関数を使用した場合、非空の結果を返すのはイニシエーターノード上のみです。

構文

getClientHTTPHeader(name)

引数

name — HTTP ヘッダーの名前。String

戻り値

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

例

使用例

SELECT getClientHTTPHeader('Content-Type');

┌─getClientHTTPHeader('Content-Type')─┐
│ application/x-www-form-urlencoded   │
└─────────────────────────────────────┘

getMacro

導入バージョン: v20.1

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

構文

getMacro(name)

引数

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

戻り値

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

例

基本的な使い方

SELECT getMacro('test');

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

getMaxTableNameLengthForDatabase

導入バージョン: v25.1

指定したデータベースにおけるテーブル名の最大文字数を返します。

構文

getMaxTableNameLengthForDatabase(database_name)

引数

database_name — 指定されたデータベースの名前。String

戻り値

テーブル名の最大長（整数）を返します。

例

基本的な例

SELECT getMaxTableNameLengthForDatabase('default');

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

getMergeTreeSetting

導入バージョン: v25.6

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

構文

getMergeTreeSetting(setting_name)

引数

setting_name — 設定の名前。String

戻り値

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

例

使用例

SELECT getMergeTreeSetting('index_granularity');

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

getOSKernelVersion

導入バージョン: v21.11

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

構文

getOSKernelVersion()

引数

なし。

返される値

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

例

使用例

SELECT getOSKernelVersion();

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

getServerPort

導入バージョン: v21.10

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

構文

getServerPort(port_name)

引数

port_name — ポートの名前。String

戻り値

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

例

使用例

SELECT getServerPort('tcp_port');

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

getServerSetting

導入バージョン: v25.6

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

構文

getServerSetting(setting_name')

引数

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

戻り値

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

例

使用例

SELECT getServerSetting('allow_use_jemalloc_memory');

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

getSetting

導入されたバージョン: v20.7

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

構文

getSetting(setting_name)

引数

setting_Name — 設定名。const String

戻り値

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

例

使用例

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

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

getSettingOrDefault

導入: v24.10

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

構文

getSettingOrDefault(setting_name, default_value)

引数

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

戻り値

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

例

使用例

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

my_value
100
NULL

getSizeOfEnumType

導入: v1.1

指定された Enum 型の要素数を返します。

構文

getSizeOfEnumType(x)

引数

x — Enum 型の値。Enum

戻り値

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

例

使用例

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

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

getSubcolumn

導入バージョン: v23.3

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

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

構文

getSubcolumn(nested_value, subcolumn_name)

引数

なし

戻り値

例

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')

getTypeSerializationStreams

導入バージョン: v22.6

データ型のストリームパスを列挙します。この関数は開発用途向けです。

構文

getTypeSerializationStreams(col)

引数

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

戻り値

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

例

tuple

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

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

map

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

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

globalVariable

導入バージョン: v20.5

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

構文

globalVariable(name)

引数

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

戻り値

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

例

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

hasColumnInTable

導入バージョン: v1.1

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

構文

hasColumnInTable([hostname[, username[, password]],]database, table, column)

引数

database — データベース名。const String
table — テーブル名。const String
column — カラム名。const String
hostname — 省略可能。チェックを実行するリモートサーバー名。const String
username — 省略可能。リモートサーバーのユーザー名。const String
password — 省略可能。リモートサーバーのパスワード。const String

戻り値

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

例

既存のカラムの確認

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

存在しないカラムを確認する

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

hasThreadFuzzer

導入バージョン: v20.6

スレッドファザー (thread fuzzer) が有効かどうかを返します。この関数はテストおよびデバッグ目的にのみ有用です。

構文

hasThreadFuzzer()

引数

なし。

返り値

Thread Fuzzer が有効かどうかを返します。UInt8

使用例

Thread Fuzzer の状態を確認

SELECT hasThreadFuzzer()

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

hostName

導入バージョン: v20.5

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

構文

hostName()

別名: hostname

引数

なし。

戻り値

ホスト名を返します。String

例

使用例

SELECT hostName()

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

icebergBucket

導入バージョン: v25.5

Iceberg の bucket transform に対応するロジックを実装します。

構文

icebergBucket(N, value)

引数

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

戻り値

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

例

SELECT icebergBucket(5, 1.0 :: Float32)

icebergTruncate

導入バージョン: v25.3

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

構文

icebergTruncate(N, value)

引数

value — 変換する値。String または (U)Int* または Decimal

戻り値

引数と同じ型です。

例

SELECT icebergTruncate(3, 'iceberg')

ice

identity

導入バージョン: v1.1

この関数は渡された引数をそのまま返します。デバッグやテストに役立ちます。索引の使用をバイパスして、フルスキャン時のパフォーマンスを確認するために利用できます。クエリアナライザは、利用する索引を検出する際に identity 関数内の内容を無視し、さらに定数畳み込み（constant folding）も無効化します。

構文

identity(x)

引数

x — 入力値。Any

戻り値

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

例

使用例

SELECT identity(42)

ignore

導入バージョン: v1.1

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

構文

ignore(x)

引数

x — 構文エラーを避けるためだけに渡される、未使用の入力値です。Any

返される値

常に 0 を返します。UInt8

例

使用例

SELECT ignore(0, 'ClickHouse', NULL)

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

indexHint

導入バージョン: v1.1

この関数はデバッグおよびイントロスペクション（内部調査）を目的としています。引数は無視され、常に 1 を返します。引数は評価されません。

索引の解析の際、この関数の引数は indexHint でラップされていないものとして扱われます。これにより、対応する条件に基づいて索引の範囲でデータを選択しつつ、その条件によるそれ以上のフィルタリングを行わないことが可能になります。 ClickHouse の索引はスパースであり、indexHint を使用すると、同じ条件を直接指定する場合よりも多くのデータが返されます。

Explanation

次のクエリを実行すると、

SELECT * FROM test WHERE key = 123;

ClickHouse は 2 つの処理を行います。

索引を使用して、どのグラニュール（約 8,192 行のブロック）が key = 123 を含む可能性があるかを特定する
それらのグラニュールを読み取り、key = 123 である行だけを返すように行ごとにフィルタリングする

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

indexHint を使って次のクエリを実行すると、

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

ClickHouse は 1 つの処理しか行いません。

索引を使用して、どのグラニュールが key = 123 を含む可能性があるかを特定し、それらのグラニュール内のすべての行をフィルタリング なしで 返す

これにより、key = 456 や key = 789 などを含む行も含めて、8,192 行すべてが返されます（同じグラニュールにたまたま格納されていたすべてのデータです）。 indexHint() は性能向上のためのものではありません。ClickHouse の索引がどのように動作するかをデバッグし、理解するためのものです。

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

注意：indexHint 関数を用いてクエリを最適化することはできません。indexHint 関数はクエリ解析に追加の情報を一切提供しないため、クエリを最適化しません。indexHint 関数の中に式を入れても、indexHint 関数を使わない場合より良くなることはまったくありません。indexHint 関数はイントロスペクションおよびデバッグ目的でのみ使用できるものであり、性能を向上させることはありません。ClickHouse のコントリビューター以外による indexHint の使用を見かけた場合、それはおそらく誤りであり、取り除くべきです。

構文

indexHint(expression)

引数

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

返される値

常に 1 を返します。UInt8

例

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

SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │    7071 │
│ 2025-09-15 │   16428 │
│ 2025-09-16 │    1077 │
│ 2025-09-30 │    8167 │
└────────────┴─────────┘

initialQueryID

導入バージョン: v1.1

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

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

構文

initialQueryID()

別名: initial_query_id

引数

なし。

戻り値

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

例

使用例

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

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initialQueryStartTime

導入バージョン: v25.4

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

構文

initialQueryStartTime()

別名: initial_query_start_time

引数

なし。

返される値

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

例

使用例

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

┌─count(DISTINCT t)─┐
│                 1 │
└───────────────────┘

initializeAggregation

導入バージョン: v20.6

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

構文

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

引数

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

戻り値

関数に渡された各行ごとの集計結果を返します。戻り値の型は、initializeAggregation が最初の引数として受け取る関数の戻り値の型と同じです。Any

例

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

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

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

sumState および finalizeAggregation との組み合わせでの使用方法

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

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

isConstant

導入バージョン: v20.3

引数が定数式かどうかを返します。定数式とは、その結果が実行前、すなわちクエリ解析中に既に分かっている式を指します。例えば、リテラルを用いた式は定数式です。この関数は主に開発、デバッグ、およびデモ用途を想定しています。

構文

isConstant(x)

引数

x — 判定する式。Any

戻り値

x が定数なら 1、定数でない場合は 0 を返します。UInt8

使用例

定数式

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

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

関数に対する定数

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

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

非定数の式

SELECT isConstant(number)
FROM numbers(1)

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

now() 関数の挙動

SELECT isConstant(now())

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

isDecimalOverflow

導入バージョン: v20.8

指定された精度の Decimal データ型に正しく収まらないほど桁数が多い小数かどうかを判定します。

構文

isDecimalOverflow(value[, precision])

引数

value — 検査対象の Decimal 値。Decimal
precision — 省略可能。Decimal 型の精度。省略した場合は、最初の引数の元の精度が使用されます。UInt8

返り値

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

例

使用例

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

┌─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

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 — 必要なデータを含むテーブルのカラム名。const String
join_keys — JOIN のキーのリスト。Any

戻り値

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

例

使用例

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

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

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

現在のデータベース内のテーブルでの利用方法

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

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

配列を結合キーとして利用する

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', 1, 11);

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

joinGetOrNull

導入: v20.4

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

注記

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

構文

joinGetOrNull(join_storage_table_name, value_column, join_keys)

引数

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

戻り値

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

例

使用例

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

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

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

lowCardinalityIndices

導入バージョン: v18.12

LowCardinality カラムの Dictionary 内における値の位置を返します。位置は 1 から始まります。LowCardinality カラムはパーツごとに Dictionary を持つため、この関数は同じ値に対しても、異なるパーツでは異なる位置を返す可能性があります。

構文

lowCardinalityIndices(col)

引数

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

戻り値

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

例

使用例

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, lowCardinalityIndices(s) FROM test;

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

lowCardinalityKeys

導入バージョン: v18.12

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

構文

lowCardinalityKeys(col)

引数

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

戻り値

Dictionary のキーを返します。UInt64

例

lowCardinalityKeys

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;

┌─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

定数を、単一の値のみを含む完全なカラムに変換します。完全なカラムと定数はメモリ上で異なる形で表現されます。関数は、通常の引数と定数引数に対して異なるコードを実行しますが、結果は一般的に同じであるべきです。この関数は、そのような挙動をデバッグするために利用できます。

構文

materialize(x)

引数

x — 定数。Any

戻り値

定数値のみから成るカラム全体を返します。Any

例

使用例

-- 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');
SELECT countMatches('foobarfoo', materialize('foo'));

2
Code: 44. DB::Exception: Received from localhost:9000. DB::Exception: Illegal type of argument #2 'pattern' of function countMatches, expected constant String, got String

minSampleSizeContinuous

導入バージョン: v23.10

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

この記事で説明されている式を使用します。介入群と対照群のサイズが等しいことを仮定します。 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*

返される値

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

例

minSampleSizeContinuous

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

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

導入バージョン: v22.6

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

この記事で説明されている式を使用します。テスト群と対照群のサイズが等しいと仮定します。1つのグループに必要なサンプルサイズを返します（すなわち、実験全体で必要となるサンプルサイズは、この返される値の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*

戻り値

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

使用例

minSampleSizeConversion

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

(3396.077603219163,0.22,0.28)

neighbor

導入バージョン: v20.1

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

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

構文

neighbor(column, offset[, default_value])

引数

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

返される値

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

例

使用例

SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

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

デフォルト値付き

SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

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

normalizeQuery

導入バージョン: v20.8

リテラル、リテラルの並び、および（空白を含むもの、2桁を超える数字を含むもの、または UUID のように長さが少なくとも 36 バイトあるものなどの）複雑なエイリアスを、プレースホルダ ? に置き換えます。

構文

normalizeQuery(x)

引数

x — 文字列。String

戻り値

指定された文字列を、プレースホルダを用いた形式で返します。String

例

使用例

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

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

normalizeQueryKeepNames

導入バージョン: v21.2

リテラルおよびリテラルの連続をプレースホルダー ? に置き換えますが、複雑なエイリアス（空白を含むもの、2 桁を超える数字を含むもの、または UUID のように少なくとも 36 バイトの長さがあるもの）は置き換えません。これにより、複雑なクエリログをより効果的に分析できます。

構文

normalizeQueryKeepNames(x)

引数

x — 文字列。String

戻り値

与えられた文字列をプレースホルダー付きで返します。String

例

使用例

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

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

normalizedQueryHash

導入バージョン: v20.8

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

構文

normalizedQueryHash(x)

引数

x — 文字列。String

戻り値

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

例

使用例

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

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

normalizedQueryHashKeepNames

導入バージョン: v21.2

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

構文

normalizedQueryHashKeepNames(x)

引数

x — 文字列。String

戻り値

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

例

使用例

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;

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

parseReadableSize

導入バージョン: v24.6

B、KiB、KB、MiB、MB など（すなわち ISO/IEC 80000-13 に準拠する単位、または 10 進バイト単位）を単位として含むバイトサイズを表す文字列が与えられた場合、この関数は対応するバイト数を返します。入力値をパースできない場合、この関数は例外をスローします。

この関数の逆の操作は formatReadableSize と formatReadableDecimalSize です。

構文

parseReadableSize(x)

引数

x — ISO/IEC 80000-13 または 10 進バイト単位で表現された可読なサイズ。String

戻り値

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

例

使用例

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

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

parseReadableSizeOrNull

導入バージョン: v24.6

バイトサイズを表す文字列で、単位として 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)

例

使用例

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

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

parseReadableSizeOrZero

導入バージョン: v24.6

B、KiB、KB、MiB、MB など（すなわち ISO/IEC 80000-13 に準拠したバイト単位、または 10進バイト単位）を単位として付与したバイトサイズ文字列を受け取り、その値に相当するバイト数を返します。入力値を解析できない場合、この関数は 0 を返します。

この関数の逆操作は formatReadableSize と formatReadableDecimalSize です。

構文

parseReadableSizeOrZero(x)

引数

x — ISO/IEC 80000-13 または 10 進バイト単位で表現された可読なサイズ。String

返される値

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

例

使用例

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

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

parseTimeDelta

導入バージョン: v22.7

時間単位を表す文字列が後続する数値列を解析します。

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

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

year と month の長さは近似値です: year は 365 日、month は 30.5 日です。

構文

parseTimeDelta(timestr)

引数

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

返される値

秒単位の数値。Float64

例

使用例

SELECT parseTimeDelta('11s+22min')

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

複雑な時間単位

SELECT parseTimeDelta('1yr2mo')

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

partitionId

導入: v21.4

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

注記

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

構文

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

別名: partitionID

引数

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

戻り値

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

例

使用例

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

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

queryID

導入バージョン: v21.9

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

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

構文

queryID()

別名: query_id

引数

なし。

戻り値

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

例

使用例

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

┌─count(DISTINCT t)─┐
│                 3 │
└───────────────────┘

revision

導入バージョン: v22.7

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

構文

revision()

引数

なし。

返り値

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

例

使用例

SELECT revision()

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

rowNumberInAllBlocks

導入されたバージョン: v1.1

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

構文

rowNumberInAllBlocks()

引数

なし。

戻り値

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

例

使用例

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

┌─rowNumberInAllBlocks()─┐
│                      0 │
│                      1 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      4 │
│                      5 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      2 │
│                      3 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      6 │
│                      7 │
└────────────────────────┘
┌─rowNumberInAllBlocks()─┐
│                      8 │
│                      9 │
└────────────────────────┘

rowNumberInBlock

導入バージョン: v1.1

rowNumberInBlock が処理する各ブロックごとに、現在の行の番号を返します。

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

構文

rowNumberInBlock()

引数

なし。

戻り値

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

例

使用例

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

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

runningAccumulate

導入バージョン: v1.1

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

非推奨

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

構文

runningAccumulate(agg_state[, grouping])

引数

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

戻り値

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

例

initializeAggregation を使用した例

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

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

runningConcurrency

導入バージョン: v21.3

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

要件

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

非推奨

代わりに window functions を使用することを推奨します。

構文

runningConcurrency(start, end)

引数

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

戻り値

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

例

使用例

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

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

runningDifference

導入バージョン: v1.1

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

Deprecated

現在処理中のデータブロック内でのみ差分を返します。このようにエラーを招きやすい挙動であるため、この関数は非推奨となっています。代わりに window functions を使用することを推奨します。

この関数の使用を許可するには、allow_deprecated_error_prone_window_functions 設定を有効にしてください。

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

構文

runningDifference(x)

引数

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

返り値

連続する値の差分を返し、最初の行には 0 を返します。

例

使用例

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

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

ブロックサイズによる影響の例

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

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

runningDifferenceStartingWithFirstValue

導入バージョン: v1.1

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

Deprecated

現在処理中のデータブロック内でのみ差分を返します。このようなエラーを招きやすい動作であるため、この関数は非推奨です。代わりに window functions（ウィンドウ関数）を使用することが推奨されます。

この関数の使用を許可するには、設定 allow_deprecated_error_prone_window_functions を有効にしてください。

構文

runningDifferenceStartingWithFirstValue(x)

引数

x — ランニング差分を計算する対象のカラム。Any

戻り値

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

例

使用例

SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

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

serverUUID

導入バージョン: v20.1

サーバーの初回起動時に生成された、ランダムで一意の UUID (v4) を返します。この UUID は保持されるため、2 回目、3 回目以降のサーバー起動でも同じ UUID が返されます。

構文

serverUUID()

引数

なし。

戻り値

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

例

使用例

SELECT serverUUID();

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

shardCount

導入バージョン: v21.9

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

構文

shardCount()

引数

なし。

戻り値

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

例

使用例

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

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

shardNum

導入バージョン: v21.9

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

構文

shardNum()

引数

なし。

戻り値

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

例

使用例

CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

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

showCertificate

導入バージョン: v22.6

現在のサーバーで Secure Sockets Layer (SSL) 証明書が構成されている場合、その情報を表示します。接続を検証するために ClickHouse を OpenSSL 証明書を用いて構成する方法の詳細については、TLS の設定を参照してください。

構文

showCertificate()

引数

なし。

戻り値

構成された SSL 証明書に関連するキーと値のペアからなるマップを返します。Map(String, String)

例

使用例

SELECT showCertificate() FORMAT LineAsString;

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

sleep

導入バージョン: v1.1

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

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

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

注意

sleep() 関数は ClickHouse システム全体のパフォーマンスや応答性に影響を与える可能性があるため、必要な場合に限り慎重に使用することが重要です。

セキュリティ上の理由から、この関数はデフォルトのユーザープロファイル（allow_sleep が有効な状態）でのみ実行できます。

構文

sleep(seconds)

引数

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

戻り値

0 を返します。UInt8

例

使用例

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

┌─sleep(2)─┐
│        0 │
└──────────┘
1 row in set. Elapsed: 2.012 sec.

sleepEachRow

導入バージョン: v1.1

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

sleepEachRow() 関数は主にテストおよびデバッグ目的で使用され、sleep() 関数と似た役割を持ちます。各行の処理に遅延や一時停止を挿入できるため、次のようなシナリオで有用です。

テスト: 特定の条件下での ClickHouse のパフォーマンスをテストまたはベンチマークする際に、sleepEachRow() を使用して各行の処理に遅延や一時停止を挿入できます。
デバッグ: 各行が処理される際のシステムの状態やクエリの実行状況を確認する必要がある場合、sleepEachRow() を使用して一時停止を挿入し、その間に関連情報を確認・収集できます。
シミュレーション: 外部システムやネットワーク遅延を扱う場合のように、各行の処理ごとに遅延や一時停止が発生する現実のシナリオをシミュレートしたいケースで利用できます。

注意

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

構文

sleepEachRow(seconds)

引数

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

戻り値

各行に対して 0 を返します。UInt8

例

使用例

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

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

structureToCapnProtoSchema

導入バージョン: v23.8

ClickHouse テーブルの構造を CapnProto 形式のスキーマに変換する関数

構文

structureToCapnProtoSchema(table_structure, message)

引数

なし

戻り値

例

random

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

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

structureToProtobufSchema

導入バージョン: v23.8

ClickHouse のテーブル構造を Protobuf 形式のスキーマに変換します。

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

構文

structureToProtobufSchema(structure, message_name)

引数

structure — ClickHouse テーブルの構造定義を文字列として指定します（例: 'column1 Type1, column2 Type2'）。String
message_name — 生成されるスキーマ内の Protobuf メッセージ型の名前。String

戻り値

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

例

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

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

syntax = "proto3";

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

tcpPort

導入バージョン: v20.12

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

構文

tcpPort()

引数

なし。

戻り値

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

例

使用例

SELECT tcpPort()

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

throwIf

導入バージョン: v1.1

引数 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

戻り値

条件が偽の場合は 0 を返し、条件が真の場合は例外を送出します。UInt8

例

使用例

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

↙ Progress: 0.00 rows, 0.00 B (0.00 rows/s., 0.00 B/s.) Received exception from server (version 19.14.1):
Code: 395. DB::Exception: Received from localhost:9000. DB::Exception: Too many.

toColumnTypeName

導入バージョン: v1.1

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

構文

toColumnTypeName(value)

引数

value — 内部データ型名を取得する対象の値。Any

返り値

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

例

使用例

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

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

toTypeName

導入バージョン: v1.1

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

構文

toTypeName(x)

引数

x — 任意の型の値。Any

戻り値

入力値のデータ型の名前を返します。String

例

使用例

SELECT toTypeName(123)

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

transactionID

導入バージョン: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

注記

この関数は実験的機能セットの一部です。 configuration に次の設定を追加して、実験的なトランザクション機能を有効にします:

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

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

構文

transactionID()

引数

なし。

戻り値

start_csn、local_tid、host_id から成るタプルを返します。

start_csn: グローバルな通番。このトランザクションの開始時点で確認された、最新のコミットタイムスタンプ。
local_tid: ローカルな通番。特定の start_csn のもとで、このホストが開始した各トランザクションごとに一意となります。
host_id: このトランザクションを開始したホストの UUID。 Tuple(UInt64, UInt64, UUID)

例

使用例

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

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

transactionLatestSnapshot

導入バージョン: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

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

注記

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

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

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

構文

transactionLatestSnapshot()

引数

なし。

戻り値

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

例

使用例

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

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

transactionOldestSnapshot

導入バージョン: v22.6

Experimental feature. Learn more.

Not supported in ClickHouse Cloud

実行中のいずれかのトランザクションに対して、そのトランザクションから可視な最も古いスナップショット（Commit Sequence Number）を返します。

注記

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

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

詳細については、トランザクション（ACID）サポートのページを参照してください。

構文

transactionOldestSnapshot()

引数

なし

戻り値

トランザクションの最古のスナップショット（CSN）を返します。 UInt64

例

使用例

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

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

transform

導入バージョン: v1.1

明示的に定義された、ある要素から別の要素へのマッピングに従って値を変換します。

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

transform(x, array_from, array_to, default) - 一致しない要素に対するデフォルト値付きで、マッピング用の配列を使って x を変換します
transform(x, array_from, array_to) - 同じ変換を行いますが、一致が見つからなかった場合は元の x を返します

この関数は array_from 内で x を検索し、同じインデックス位置にある array_to の対応する要素を返します。 x が array_from 内に見つからない場合、4 引数バージョンでは default 値を、3 引数バージョンでは元の x を返します。 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

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM test.hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC

┌─title─────┬──────c─┐
│ Yandex    │ 498635 │
│ Google    │ 229872 │
│ Other     │ 104472 │
└───────────┴────────┘

transform(T, Array(T), Array(T)) -> T

SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM test.hits
GROUP BY domain(Referer)
ORDER BY count() DESC
LIMIT 10

┌─s──────────────┬───────c─┐
│                │ 2906259 │
│ www.yandex     │  867767 │
│ ███████.ru     │  313599 │
│ mail.yandex.ru │  107147 │
│ ██████.ru      │  100355 │
│ █████████.ru   │   65040 │
│ news.yandex.ru │   64515 │
│ ██████.net     │   59141 │
│ example.com    │   57316 │
└────────────────┴─────────┘

uniqThetaIntersect

導入バージョン: v22.9

2つの uniqThetaSketch オブジェクトの共通部分（集合演算 ∩）を計算し、その結果として新しい uniqThetaSketch を返します。

構文

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

引数

uniqThetaSketch — uniqThetaSketch オブジェクト。Tuple または Array または Date または DateTime または String または (U)Int* または Float* または Decimal

戻り値

共通部分（インターセクト）の結果を含む新しい uniqThetaSketch。UInt64

例

使用例

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

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

uniqThetaNot

導入: v22.9

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

例

使用例

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

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

uniqThetaUnion

導入バージョン: v22.9

2 つの uniqThetaSketch オブジェクトに対して和集合（集合演算 ∪）を計算し、その結果として新しい uniqThetaSketch オブジェクトを返します。

構文

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

引数

uniqThetaSketch — uniqThetaSketch オブジェクト。Tuple、Array、Date、DateTime、String、(U)Int*、Float*、または Decimal のいずれか。

戻り値

和集合の結果を保持する新しい uniqThetaSketch を返します。戻り値の型は UInt64 です。

例

使用例

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

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

uptime

導入バージョン: v1.1

サーバーの稼働時間を秒単位で返します。分散テーブルのコンテキストで実行された場合、この関数は各分片に対応する値を持つ通常のカラムを生成します。それ以外の場合は、定数値を返します。

構文

uptime()

引数

なし。

返り値

サーバーの稼働時間を秒単位で返します。 UInt32

例

使用例

SELECT uptime() AS Uptime

┌─Uptime─┐
│  55867 │
└────────┘

variantElement

バージョン v25.2 で導入。

Variant カラムから、指定した型を持つカラムを抽出します。

構文

variantElement(variant, type_name[, default_value])

引数

variant — Variant カラム。Variant
type_name — 抽出する Variant 型の名前。String
default_value — 指定された型の Variant が存在しない場合に使用されるデフォルト値。任意の型を指定可能なオプション引数。Any

返り値

Variant カラムから指定された Variant 型を抽出したカラムを返します。Any

例

使用例

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

variantType

導入バージョン: v24.2

Variant カラムの各行に対して、その Variant 型の名前を返します。行に NULL が含まれている場合、その行については 'None' を返します。

構文

variantType(variant)

引数

variant — Variant 型のカラム。Variant

戻り値

各行ごとに、Variant 型名を格納した Enum 型のカラムを返します。Enum

例

使用例

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

version

導入バージョン: v1.1

現在の ClickHouse のバージョンを、major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release という形式の文字列として返します。分散テーブルのコンテキストで実行する場合、この関数は各分片に対応する値を持つ通常のカラムを生成します。それ以外の場合は、定数値を返します。

構文

version()

引数

なし。

戻り値

現在の ClickHouse のバージョンを返します。String

例

使用例

SELECT version()

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

visibleWidth

導入バージョン: v1.1

値をテキスト形式（タブ区切り）でコンソールに出力したときのおおよその幅を計算します。この関数は、システムが Pretty 形式を実装する際に使用されます。 NULL は、Pretty 形式における NULL に対応する文字列として表現されます。

構文

visibleWidth(x)

引数

x — 任意のデータ型の値。Any

戻り値

値をテキスト形式で表示したときのおおよその表示幅を返します。UInt64

例

NULL の表示幅を計算

SELECT visibleWidth(NULL)

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

zookeeperSessionUptime

導入バージョン: v21.11

現在の ZooKeeper セッションの稼働時間（秒）を返します。

構文

zookeeperSessionUptime()

引数

なし。

戻り値

現在の ZooKeeper セッションの稼働時間を秒単位で返します。UInt32

例

使用例

SELECT zookeeperSessionUptime();

┌─zookeeperSessionUptime()─┐
│                      286 │
└──────────────────────────┘

FQDN​

MACNumToString​

MACStringToNum​

MACStringToOUI​

authenticatedUser​

bar​

blockNumber​

blockSerializedSize​

blockSize​

buildId​

byteSize​

catboostEvaluate​

colorOKLABToSRGB​

colorOKLCHToSRGB​

colorSRGBToOKLAB​

colorSRGBToOKLCH​

connectionId​

countDigits​

currentDatabase​

currentProfiles​

currentQueryID​

currentRoles​

currentSchemas​

currentUser​

defaultProfiles​

defaultRoles​

defaultValueOfArgumentType​

defaultValueOfTypeName​

displayName​

dumpColumnStructure​

enabledProfiles​

enabledRoles​

errorCodeToName​

file​

filesystemAvailable​

filesystemCapacity​

filesystemUnreserved​

finalizeAggregation​

flipCoordinates​

formatQuery​

formatQueryOrNull​

formatQuerySingleLine​

formatQuerySingleLineOrNull​

formatReadableDecimalSize​

formatReadableQuantity​

formatReadableSize​

formatReadableTimeDelta​

fuzzQuery​

generateRandomStructure​

generateSerialID​

getClientHTTPHeader​

getMacro​

getMaxTableNameLengthForDatabase​

getMergeTreeSetting​

getOSKernelVersion​

getServerPort​

getServerSetting​

getSetting​

getSettingOrDefault​

getSizeOfEnumType​

getSubcolumn​

getTypeSerializationStreams​

globalVariable​

hasColumnInTable​

hasThreadFuzzer​

hostName​

icebergBucket​

icebergTruncate​

identity​

ignore​

indexHint​

initialQueryID​

initialQueryStartTime​

initializeAggregation​

isConstant​

isDecimalOverflow​

joinGet​

joinGetOrNull​

lowCardinalityIndices​

lowCardinalityKeys​

FQDN

MACNumToString

MACStringToNum

MACStringToOUI

authenticatedUser

bar

blockNumber

blockSerializedSize

blockSize

buildId

byteSize

catboostEvaluate

colorOKLABToSRGB

colorOKLCHToSRGB

colorSRGBToOKLAB

colorSRGBToOKLCH

connectionId

countDigits

currentDatabase

currentProfiles

currentQueryID

currentRoles

currentSchemas

currentUser

defaultProfiles

defaultRoles

defaultValueOfArgumentType

defaultValueOfTypeName

displayName

dumpColumnStructure

enabledProfiles

enabledRoles

errorCodeToName

file

filesystemAvailable

filesystemCapacity

filesystemUnreserved

finalizeAggregation

flipCoordinates

formatQuery

formatQueryOrNull

formatQuerySingleLine

formatQuerySingleLineOrNull

formatReadableDecimalSize

formatReadableQuantity

formatReadableSize

formatReadableTimeDelta

fuzzQuery

generateRandomStructure

generateSerialID

getClientHTTPHeader

getMacro

getMaxTableNameLengthForDatabase

getMergeTreeSetting

getOSKernelVersion

getServerPort

getServerSetting

getSetting

getSettingOrDefault

getSizeOfEnumType

getSubcolumn

getTypeSerializationStreams

globalVariable

hasColumnInTable

hasThreadFuzzer

hostName

icebergBucket

icebergTruncate

identity

ignore

indexHint

initialQueryID

initialQueryStartTime

initializeAggregation

isConstant

isDecimalOverflow

joinGet

joinGetOrNull

lowCardinalityIndices

lowCardinalityKeys