その他の関数
hostName
この関数が実行されたホストの名前を返します。関数がリモートサーバーで実行される場合（分散処理）、リモートサーバーの名前が返されます。 関数が分散テーブルのコンテキスト内で実行されると、各シャードに関連する値を持つ通常のカラムを生成します。それ以外の場合は一定の値を生成します。
構文
返される値
- ホスト名。String。
getMacro
サーバー構成のマクロセクションから名前付きの値を返します。
構文
引数
name—<macros>セクションから取得するマクロ名。String.
返される値
- 指定されたマクロの値。String。
例
サーバー構成ファイルの例<macros>セクション：
クエリ：
結果：
同じ値を以下のように取得することができます：
fqdn
ClickHouseサーバーの完全修飾ドメイン名を返します。
構文
別名: fullHostName, FQDN。
返される値
- 完全修飾ドメイン名を含む文字列。String。
例
結果：
basename
最後のスラッシュまたはバックスラッシュの後の文字列を抽出します。この関数は、パスからファイル名を抽出するためによく使用されます。
引数
expr— String型の値。バックスラッシュはエスケープする必要があります。
返される値
次を含む文字列：
- 最後のスラッシュまたはバックスラッシュの後の入力文字列の尾部。入力文字列がスラッシュまたはバックスラッシュで終わる場合（例：
/またはc:\）、関数は空の文字列を返します。 - スラッシュまたはバックスラッシュがない場合は元の文字列。
例
クエリ：
結果：
クエリ：
結果：
クエリ：
結果：
visibleWidth
値をテキスト形式（タブ区切り）でコンソールに出力する際の概算の幅を計算します。 この関数は、Prettyフォーマットを実装するためにシステムによって使用されます。
NULLは、PrettyフォーマットでNULLに対応する文字列として表されます。
構文
例
クエリ：
結果：
toTypeName
渡された引数の型名を返します。
NULLが渡された場合、関数は型Nullable(Nothing)を返します。これはClickHouseの内部NULL表現に対応します。
構文
引数
value— 任意の型の値。
返される値
- 入力値のデータ型名。String。
例
クエリ：
結果：
blockSize
ClickHouseにおいて、クエリはブロック（チャンク）単位で処理されます。 この関数は、関数が呼び出されたブロックのサイズ（行数）を返します。
構文
例
クエリ：
結果：
byteSize
メモリ内の引数の圧縮されていないバイトサイズの推定を返します。
構文
引数
argument— 値。
返される値
- メモリ内の引数のバイトサイズの推定値。UInt64。
例
String引数に対して、関数は文字列の長さ+9（終端ゼロ+長さ）を返します。
クエリ：
結果：
クエリ：
結果：
関数に複数の引数がある場合、関数はそれらのバイトサイズを合算します。
クエリ：
結果：
materialize
定数を単一の値を含む完全なカラムに変換します。 完全なカラムと定数はメモリ内で異なる方法で表現されます。 関数は通常、通常の引数と定数引数に対して異なるコードを実行しますが、結果は通常同じであるべきです。 この関数は、この動作をデバッグするために使用できます。
構文
パラメータ
x— 定数。Constant。
返される値
- 単一の値
xを含むカラム。
例
以下の例では、countMatches関数は定数の2番目の引数を期待します。
この動作は、materialize関数を使用して定数を完全なカラムに変換することでデバッグでき、関数が非定数引数に対してエラーをスローすることを確認できます。
クエリ：
結果：
ignore
任意の引数を受け入れ、無条件に0を返します。
引数は内部で評価されるため、ベンチマーキングに便利です。
構文
引数
- 任意の型の任意の数の引数を受け入れ、
NULLも含まれます。
返される値
0を返します。
例
クエリ：
結果：
sleep
クエリの実行に遅延や停止を導入するために使用されます。主にテストやデバッグの目的で使用されます。
構文
引数
返される値
この関数は値を返しません。
例
この関数は値を返しません。しかし、clickhouse clientを使用して関数を実行すると、次のような結果が表示されます：
このクエリは完了するまでに2秒間停止します。この間、結果は返されず、クエリはハングしているか反応しないように見えるでしょう。
実装の詳細
sleep()関数は、クエリのパフォーマンスやシステムの応答性に悪影響を及ぼす可能性があるため、一般的には本番環境では使用されません。しかし、以下のシナリオで役立つ場合があります：
- テスト: ClickHouseのテストやベンチマーキング中に、遅延をシミュレーションしたり、特定の条件下でシステムの挙動を観察するために使用できます。
- デバッグ: 特定の時点でシステムの状態やクエリの実行を調べる必要がある場合、
sleep()を使用して遅延を導入し、関連情報を検査したり収集したりできます。 - シミュレーション: ネットワーク遅延や外部システムへの依存など、実世界のシナリオでの遅延をシミュレーションする場合にも役立ちます。
sleep()関数を使用する際は、必要に応じて適切に使用し、ClickHouseシステムの全体的な性能や応答性に影響を与えないようにすることが重要です。
sleepEachRow
結果セットの各行に対して指定された秒数だけクエリの実行を停止します。
構文
引数
返される値
この関数は受け取った入力値と同じ値を返し、変更は行いません。
例
出力は遅延しますが、各行の間に0.5秒の停止があります。
sleepEachRow()関数は、sleep()関数と同様に主にテストやデバッグ目的で使用されます。各行の処理に遅延をシミュレートしたり、遅延を導入することができます。これが役立つシナリオには以下があります：
- テスト: 特定の条件下でのClickHouseのパフォーマンスをテストまたはベンチマーキングするとき、各行処理のために遅延をシミュレートしたり導入するために
sleepEachRow()を使用できます。 - デバッグ: 各行処理時にシステムの状態やクエリの実行を調べる必要がある場合、
sleepEachRow()を使用して遅延を導入し、関連情報を検査したり収集したりできます。 - シミュレーション: 外部システムやネットワークの遅延を扱う際など、各行処理に遅延が発生する実世界のシナリオをシミュレートしたい場合にも役立つことがあります。
sleepEachRow()関数もsleep()関数同様に慎重に使用することが重要で、特に大きな結果セットではClickHouseシステムの全体的なパフォーマンスと応答性に大きく影響を与える可能性があります。
currentDatabase
現在のデータベースの名前を返します。
CREATE TABLEクエリのテーブルエンジンパラメータでデータベースを指定する際に便利です。
構文
返される値
- 現在のデータベース名。String。
例
クエリ：
結果：
currentUser
現在のユーザーの名前を返します。分散クエリの場合、クエリを開始したユーザーの名前が返されます。
構文
別名: user(), USER(), current_user()。別名はケースを区別しません。
返される値
例
結果：
currentSchemas
現在のデータベーススキーマの名前を含む単一要素の配列を返します。
構文
別名: current_schemas。
引数
bool: ブール値。Bool。
ブール引数は無視されます。これは、PostgreSQLでのこの関数の実装との互換性のためだけに存在します。
返される値
- 現在のデータベースの名前を含む単一要素の配列を返します。
例
結果：
isConstant
引数が定数式であるかどうかを返します。
定数式とは、クエリ解析中に結果が既知の式、すなわち実行前に評価される式です。例えば、リテラルに対する式は定数式です。
この関数は、主に開発、デバッグ、デモの目的で使用されます。
構文
引数
x— チェックする式。
返される値
例
クエリ：
結果：
クエリ：
結果：
クエリ：
結果：
hasColumnInTable
データベース名、テーブル名、カラム名を定数文字列として与えると、指定したカラムが存在すれば1を返し、そうでなければ0を返します。
構文
パラメーター
database: データベースの名前。String literaltable: テーブルの名前。String literalcolumn: カラムの名前。String literalhostname: チェックを行うリモートサーバーの名前。String literalusername: リモートサーバーのユーザー名。String literalpassword: リモートサーバーのパスワード。String literal
返される値
- 指定されたカラムが存在すれば
1。 - そうでなければ
0。
実装の詳細
ネストされたデータ構造内の要素について、関数はカラムの存在を確認します。ネストされたデータ構造自体に対しては、関数は0を返します。
例
クエリ：
hasThreadFuzzer
スレッドファジングが効果的であるかどうかを返します。テストで実行が長くなりすぎないように防ぐために使用できます。
構文
bar
バーチャートを描画します。
bar(x, min, max, width)は、幅が(x - min)に比例し、x = maxのときに幅がwidth文字になるバンドを描画します。
引数
x— 表示するサイズ。min, max— 整数定数。値はInt64に収まる必要があります。width— 定数の正の整数で、小数を指定することもできます。
バンドは、シンボルの8分の1に精度を持って描かれます。
例：
transform
明示的に定義されたマッピングに従って値を変換します。 この関数には2つのバリエーションがあります：
transform(x, array_from, array_to, default)
x – 変換する値。
array_from – 変換する定数の配列。
array_to – fromの値を変換するための定数配列。
default – xがfromのいずれの値とも等しくない場合に使用する値。
array_fromとarray_toは同数の要素を持たなければなりません。
署名:
transform(T, Array(T), Array(U), U) -> U
TとUは数値、文字列、またはDate型またはDateTime型です。同じ文字（TまたはU）は、互換性があるが必ずしも等しくない型を示します。
例えば、最初の引数の型がInt64で、2番目の引数の型がArray(UInt16)であることができます。
例：
transform(x, array_from, array_to)
他のバリエーションと類似しますが、default引数がありません。一致するものが見つからなかった場合、xが返されます。
例：
formatReadableDecimalSize
サイズ（バイト数）を指定すると、この関数は読みやすく、丸められたサイズをサフィックス（KB、MBなど）付きの文字列として返します。
この関数の逆操作は、parseReadableSize、parseReadableSizeOrZero、およびparseReadableSizeOrNullです。
構文
例
クエリ：
結果：
formatReadableSize
サイズ（バイト数）を指定すると、この関数は読みやすく、丸められたサイズをサフィックス（KiB、MiBなど）付きの文字列として返します。
この関数の逆操作は、parseReadableSize、parseReadableSizeOrZero、およびparseReadableSizeOrNullです。
構文
別名: FORMAT_BYTES。
この関数は入力として任意の数値型を受け入れますが、内部的にはFloat64にキャストされます。大きな値に対しては結果が最適でない場合があります。
例
クエリ：
結果：
formatReadableQuantity
数値を指定すると、この関数はサフィックス（千、百万、十億など）を付けた丸められた数値を文字列として返します。
構文
この関数は入力として任意の数値型を受け付けますが、内部的にはFloat64にキャストされます。大きな値に対して最適な結果が得られない可能性があります。
例
クエリ：
結果：
formatReadableTimeDelta
時間間隔（デルタ）を秒単位で指定すると、この関数は年/月/日/時/分/秒/ミリ秒/マイクロ秒/ナノ秒としての時間デルタを文字列で返します。
構文
この関数は任意の数値型を受け入れますが、内部的にはFloat64にキャストされます。大きな値に対して結果が最適でない可能性があります。
引数
column— 数値の時間デルタを持つカラム。maximum_unit— オプション。表示する最大単位。- 許容される値:
nanoseconds,microseconds,milliseconds,seconds,minutes,hours,days,months,years。 - デフォルト値:
years。
- 許容される値:
minimum_unit— オプション。表示する最小単位。すべての小さい単位は切り捨てられます。- 許容される値:
nanoseconds,microseconds,milliseconds,seconds,minutes,hours,days,months,years。 - 明示的に指定された値が
maximum_unitよりも大きい場合、例外がスローされます。 - デフォルト値:
secondsはmaximum_unitがsecondsかそれ以上の場合、そうでなければnanoseconds。
- 許容される値:
例
parseReadableSize
バイトサイズを含む文字列およびB、KiB、KB、MiB、MBなどの単位を指定すると、この関数は対応するバイト数を返します。
関数が入力値をパースできない場合、例外をスローします。
この関数の逆操作は、formatReadableSizeとformatReadableDecimalSizeです。
構文
引数
x: ISO/IEC 80000-13または10進バイト単位の読みやすいサイズ(String)。
返される値
- バイト数で、最近接の整数に丸められます(UInt64)。
例
parseReadableSizeOrNull
バイトサイズを含む文字列およびB、KiB、KB、MiB、MBなどの単位を指定すると、この関数は対応するバイト数を返します。
関数が入力値をパースできない場合、NULLを返します。
この関数の逆操作は、formatReadableSizeとformatReadableDecimalSizeです。
構文
引数
x: ISO/IEC 80000-13または10進バイト単位の読みやすいサイズ(String)。
返される値
- バイト数で、最近接の整数に丸められます。または、入力をパースできない場合はNULL（Nullable(UInt64)）。
例
parseReadableSizeOrZero
バイトサイズを含む文字列およびB、KiB、KB、MiB、MBなどの単位を指定すると、この関数は対応するバイト数を返します。
関数が入力値をパースできない場合、0を返します。
この関数の逆操作は、formatReadableSizeとformatReadableDecimalSizeです。
構文
引数
x: ISO/IEC 80000-13または10進バイト単位の読みやすいサイズ(String)。
返される値
- バイト数で、最近接の整数に丸められます。または、入力をパースできない場合は0(UInt64)。
例
parseTimeDelta
数値の列を解析し、時間単位に似たものを続けて返します。
構文
引数
timestr— 時間単位に似たものを伴う数値の列。
返される値
- 秒数の浮動小数点数。
例
least
1つまたは複数の入力引数の中で最小の引数を返します。 NULL引数は無視されます。
構文
バージョン 24.12 では、 NULL値が無視されるという後方互換性のない変更が導入され、以前は引数の1つが NULLの場合は NULLを返していました。以前の動作を保持するには、設定 least_greatest_legacy_null_behavior（デフォルト: false）を trueに設定してください。
greatest
1つまたは複数の入力引数の中で最大の引数を返します。 NULL引数は無視されます。
構文
バージョン 24.12 では、 NULL値が無視されるという後方互換性のない変更が導入され、以前は引数の1つが NULLの場合は NULLを返していました。以前の動作を保持するには、設定 least_greatest_legacy_null_behavior（デフォルト: false）を trueに設定してください。
uptime
サーバーの稼働時間を秒単位で返します。 分散テーブルの文脈で実行されると、この関数は各シャードに関連する値を持つ通常のカラムを生成します。そうでない場合は、一定の値を生成します。
構文
返される値
- 秒単位の時間値。UInt32。
例
クエリ:
結果:
version
ClickHouseの現在のバージョンを、次の形式の文字列で返します。
- メジャーバージョン
- マイナーバージョン
- パッチバージョン
- 前の安定リリースからのコミット数。
分散テーブルの文脈で実行されると、この関数は各シャードに関連する値を持つ通常のカラムを生成します。そうでない場合は、一定の値を生成します。
構文
引数
なし。
返される値
- ClickHouseの現在のバージョン。String。
実装の詳細
なし。
例
クエリ:
結果:
buildId
実行中のClickHouseサーバーバイナリのコンパイラによって生成されたビルドIDを返します。 分散テーブルの文脈で実行されると、この関数は各シャードに関連する値を持つ通常のカラムを生成します。そうでない場合は、一定の値を生成します。
構文
blockNumber
行を含むブロックの単調増加するシーケンス番号を返します。 返されるブロック番号は、最善の努力に基づいて更新されます。つまり、完全に正確でない可能性があります。
構文
返される値
- 行が含まれるデータブロックのシーケンス番号。UInt64。
例
クエリ:
結果:
rowNumberInBlock
rowNumberInBlockによって処理された各ブロックの現在の行の番号を返します。
返される番号は各ブロックで0から始まります。
構文
返される値
- データブロック内の行の序数番号（0から始まる）。UInt64。
例
クエリ:
結果:
rowNumberInAllBlocks
rowNumberInAllBlocksによって処理された各行に対して一意の行番号を返します。返される番号は0から始まります。
構文
返される値
- データブロック内の行の序数番号（0から始まる）。UInt64。
例
クエリ:
結果:
normalizeQuery
リテラル、リテラルの列、複雑なエイリアス（空白、2桁以上または少なくとも36バイトの長さを持つUUIDを含む）をプレースホルダー ? に置き換えます。
構文
引数
x— 文字の列。String。
返される値
- プレースホルダーを持つ文字の列。String。
例
クエリ:
結果:
normalizeQueryKeepNames
リテラル、リテラルの列をプレースホルダー ? に置き換えますが、複雑なエイリアス（空白、2桁以上または少なくとも36バイトの長さを持つUUIDを含む）は置き換えません。これにより複雑なクエリログをより良く分析できます。
構文
引数
x— 文字の列。String。
返される値
- プレースホルダーを持つ文字の列。String。
例
クエリ:
結果:
normalizedQueryHash
リテラルの値を含まない同一の64ビットハッシュ値を、類似のクエリに対して返します。クエリログの分析に役立ちます。
構文
引数
x— 文字の列。String。
返される値
- ハッシュ値。UInt64。
例
クエリ:
結果:
normalizedQueryHashKeepNames
normalizedQueryHash と同様に、リテラルの値を含まない同一の64ビットハッシュ値を類似のクエリに対して返しますが、ハッシュ化の前に複雑なエイリアス（空白、2桁以上または少なくとも36バイトの長さを持つUUIDを含む）をプレースホルダーに置き換えません。クエリログの分析に役立ちます。
構文
引数
x— 文字の列。String。
返される値
- ハッシュ値。UInt64。
例
結果:
neighbor
指定されたオフセット前後の現在の行にアクセスするウィンドウ関数です。
構文
この関数の結果は、影響を受けるデータブロックとブロック内のデータの順序によって異なります。
現在処理中のデータブロック内の隣接行のみを返します。 このエラーを引き起こす可能性のある動作のため、この関数は非推奨です。正しいウィンドウ関数を代わりに使用してください。
neighbor()の計算中に行の順序が、ユーザーに返される行の順序と異なる場合があります。
これを防ぐためには、ORDER BYでサブクエリを作成し、サブクエリの外部から関数を呼び出すことができます。
引数
column— カラム名またはスカラー式。offset— 現在の行のcolumnの前または後ろを見る行数。Int64。default_value— オプション。オフセットがブロック境界外に出た場合の返される値。影響を受けるデータブロックの型。
返される値
- 現在の行から
offsetの距離を持つcolumnの値、もしoffsetがブロック境界内に収まっていれば。 - ブロック境界の外にオフセットがある場合は、
columnのデフォルト値またはdefault_value（指定した場合）。
返される型は、影響を受けるデータブロックの型またはデフォルト値の型になります。
例
クエリ:
結果:
クエリ:
結果:
この関数は、年ごとのメトリック値を計算するために使用できます。
クエリ:
結果:
runningDifference
データブロック内の2つの連続した行値の差を計算します。 最初の行では0を返し、その後の行では前の行との差を返します。
現在処理中のデータブロック内でのみ差を返します。 このエラーを引き起こす可能性のある動作のため、この関数は非推奨です。正しいウィンドウ関数を代わりに使用してください。
この関数の結果は、影響を受けるデータブロックとブロック内のデータの順序によって異なります。
runningDifference()の計算中に行の順序が、ユーザーに返される行の順序と異なる場合があります。
これを防ぐためには、ORDER BYでサブクエリを作成し、サブクエリの外部から関数を呼び出すことができます。
構文
例
クエリ:
結果:
ブロックサイズが結果に影響を与えることに注意してください。 runningDifferenceの内部状態は、新しいブロックごとにリセットされます。
クエリ:
結果:
クエリ:
結果:
runningDifferenceStartingWithFirstValue
この関数は非推奨です（runningDifferenceのノートを参照）。
runningDifference と同様ですが、最初の行の値を最初の行の値として返します。
runningConcurrency
同時に発生するイベント数を計算します。 各イベントには開始時刻と終了時刻があります。開始時刻はイベントに含まれ、終了時刻は含まれません。開始時刻と終了時刻を持つカラムは同じデータ型である必要があります。 この関数は、各イベント開始時刻の総アクティブ（同時）イベント数を計算します。
イベントは開始時刻の昇順で整列されている必要があります。この要件が満たされていない場合、関数は例外を発生させます。すべてのデータブロックは別々に処理されます。異なるデータブロックのイベントが重複している場合、正しく処理できません。
構文
引数
start— イベントの開始時刻を持つカラム。Date、DateTime、またはDateTime64。end— イベントの終了時刻を持つカラム。Date、DateTime、またはDateTime64。
返される値
- 各イベント開始時刻における同時イベントの数。UInt32
例
テーブルを考慮:
クエリ:
結果:
MACNumToString
UInt64の数値をビッグエンディアン形式のMACアドレスとして解釈します。対応するMACアドレスを、AA:BB:CC:DD:EE:FF（16進数形式でコロン区切りの数値）の形式で文字列として返します。
構文
MACStringToNum
MACNumToStringの逆関数です。MACアドレスが無効な形式の場合、0を返します。
構文
MACStringToOUI
AA:BB:CC:DD:EE:FF（16進数形式でコロン区切りの数値）形式のMACアドレスを取得し、最初の3オクテットをUInt64の数値として返します。MACアドレスが無効な形式の場合、0を返します。
構文
getSizeOfEnumType
Enum内のフィールド数を返します。
型が Enumでない場合は例外がスローされます。
構文
引数:
value—Enum型の値。
返される値
Enum入力値を持つフィールドの数。
例
blockSerializedSize
圧縮を考慮せずにディスク上のサイズを返します。
引数
value— 任意の値。
返される値
- 圧縮なしで値のブロックのディスクへの書き込みに必要なバイト数。
例
クエリ:
結果:
toColumnTypeName
値を表すデータ型の内部名を返します。
構文
引数:
value— 任意の型の値。
返される値
valueを表現するために使用される内部データ型名。
例
toTypeNameとtoColumnTypeNameの違い:
結果:
クエリ:
結果:
この例は、DateTimeデータ型が内部的に Const(UInt32)として保存されることを示しています。
dumpColumnStructure
RAM内のデータ構造の詳細な説明を出力します。
引数:
value— 任意の型の値。
返される値
valueを表すために使用されるカラム構造の説明。
例
defaultValueOfArgumentType
指定されたデータ型のデフォルト値を返します。
ユーザーによって設定されたカスタムカラムのデフォルト値は含まれません。
構文
引数:
expression— 任意の型の値または任意の型の値を結果として生成する式。
返される値
- 数値の場合は
0。 - 文字列の場合は空の文字列。
- Nullableの場合は
ᴺᵁᴸᴸ。
例
クエリ:
結果:
クエリ:
結果:
defaultValueOfTypeName
指定された型名のデフォルト値を返します。
ユーザーによって設定されたカスタムカラムのデフォルト値は含まれません。
引数:
type— 型名を表す文字列。
返される値
- 数値の場合は
0。 - 文字列の場合は空の文字列。
- Nullableの場合は
ᴺᵁᴸᴸ。
例
クエリ:
結果:
クエリ:
結果:
indexHint
この関数はデバッグと内部調査を目的としています。引数を無視し、常に1を返します。引数は評価されません。
しかし、インデックス分析中に、この関数の引数は indexHintでラップされていないと見なされます。これにより、フルフィルタリングを行わずに対応する条件によってインデックス範囲内のデータを選択できます。ClickHouseのインデックスはスパースであり、indexHintを使用すると、直接条件を指定するよりも多くのデータが得られます。
構文
返される値
1。Uint8。
例
テーブルontimeからのテストデータの例です。
テーブル:
テーブルにはフィールド (FlightDate, (Year, FlightDate)) にインデックスがあります。
インデックスを使用しないクエリを作成します:
ClickHouseはテーブル全体を処理しました（Processed 4.28 million rows）。
結果:
特定の日付を選択してインデックスを適用します:
ClickHouseは、処理する行数が大幅に少なくなりました（Processed 32.74 thousand rows）。
結果:
次に、k = '2017-09-15'式を indexHint関数でラップします:
クエリ:
ClickHouseは以前と同様にインデックスを使用しました（Processed 32.74 thousand rows）。
結果を生成する際には、式 k = '2017-09-15'は使用されませんでした。
例では、indexHint関数を使用することで隣接する日付を確認できます。
結果:
replicate
単一の値を持つ配列を作成します。
この関数は arrayJoinの内部実装に使用されます。
構文
引数
x— 結果の配列に埋め込む値。arr— 配列。Array。
返される値
arrと同じ長さの配列で、値 xで埋められています。Array。
例
クエリ:
結果:
revision
現在のClickHouse サーバーのリビジョンを返します。
構文
返される値
- 現在のClickHouseサーバーのリビジョン。UInt32。
例
クエリ:
結果:
filesystemAvailable
データベースの永続性をホストしているファイルシステム内の空き容量を返します。返される値は、OSのために予約されたスペースがあるため、常に総空き容量（filesystemUnreserved）よりも小さいです。
構文
返される値
- バイト単位で利用可能な残りスペースの量。UInt64。
例
クエリ:
結果:
filesystemUnreserved
データベースの永続性をホストしているファイルシステム内の総空き容量を返します。（以前は filesystemFree）。 filesystemAvailableも参照してください。
構文
返される値
- バイト単位での空き容量。UInt64。
例
クエリ:
結果:
filesystemCapacity
ファイルシステムの容量をバイト単位で返します。データディレクトリへのパスを設定する必要があります。
構文
返される値
- バイト単位でのファイルシステムの容量。UInt64。
例
クエリ:
結果:
initializeAggregation
単一の値に基づいて集約関数の結果を計算します。この関数は、-Stateのある集約関数を初期化するために使用されます。集約関数の状態を作成し、それをAggregateFunction型のカラムに挿入したり、初期化された集約をデフォルト値として使用したりできます。
構文
引数
aggregate_function— 初期化する集約関数の名前。String。arg— 集約関数の引数。
返される値
- 関数に渡された各行に対する集約の結果。
返される型は、initializeAggregationが最初の引数として取る関数の返される型と同じです。
例
クエリ:
結果:
クエリ:
結果:
AggregatingMergeTreeテーブルエンジンとAggregateFunctionカラムを使った例:
関連項目
引数
state— 集計の状態。AggregateFunction。
返される値
- 集計された値。
戻り値の型は、集計された任意の型と等しいです。
例
クエリ:
結果:
クエリ:
結果:
NULL 値は無視されることに注意してください。
クエリ:
結果:
組み合わせた例:
クエリ:
結果:
参照
runningAccumulate
データブロックの各行に対して集計関数の状態を累積します。
データの新しいブロックごとに状態がリセットされます。この動作はエラープロンなため、関数は非推奨とされており、適切なウィンドウ関数を代わりに使用してください。
構文
引数
agg_state— 集計関数の状態。AggregateFunction。grouping— グルーピングキー。オプション。groupingの値が変更されると、関数の状態はリセットされます。等価演算子が定義されているサポートされているデータ型のいずれかである必要があります。
返される値
- 各結果行には、入力行から現在の位置までの累積結果が含まれます。
runningAccumulateは、新しいデータブロックごとに状態やgroupingの値が変更されるたびにリセットされます。
使用される集計関数に応じて型は異なります。
例
runningAccumulateを使用して、グルーピングなしおよびグルーピングありで数値の累積和を求める方法を考えてみましょう。
クエリ:
結果:
サブクエリは、0から9までの各数に対してsumStateを生成します。sumStateは、単一の数の合計を含むsum関数の状態を返します。
全体のクエリは以下のようになります:
- 最初の行では、
runningAccumulateはsumState(0)を使用して0を返します。 - 2行目では、関数は
sumState(0)とsumState(1)をマージし、sumState(0 + 1)を生成し、結果として1を返します。 - 3行目では、関数は
sumState(0 + 1)とsumState(2)をマージし、sumState(0 + 1 + 2)を生成し、結果として3を返します。 - この動作はブロックが終了するまで繰り返されます。
以下の例は、groupingパラメータの使用法を示しています。
クエリ:
結果:
ご覧のとおり、runningAccumulateは行の各グループの状態を別々にマージします。
joinGet
この関数は、テーブルから辞書のようにデータを抽出することを許可します。Joinテーブルから指定された結合キーを使用してデータを取得します。
ENGINE = Join(ANY, LEFT, <join_keys>)ステートメントで作成されたテーブルのみをサポートします。
構文
引数
join_storage_table_name— 検索が行われる識別子。value_column— 必要なデータを含むテーブルのカラムの名前。join_keys— キーのリスト。
識別子はデフォルトのデータベース内で検索されます（設定ファイルの default_database を参照）。デフォルトのデータベースを上書きするには、USE db_nameを使用するか、データベースとテーブルを区切り文字 db_name.db_table を使用して指定します。
返される値
- キーのリストに対応する値のリストを返します。
特定のキーがソーステーブルに存在しない場合、テーブル作成時のjoin_use_nulls設定に基づき、0またはnullが返されます。
join_use_nullsの詳細はJoin operationを参照してください。
例
入力テーブル:
クエリ:
結果:
join_use_nulls設定を使用することは、ソーステーブルにキーが存在しない場合の戻り値の動作を変更するために使用できます。
クエリ:
結果:
joinGetOrNull
joinGetに似ていますが、キーが欠けている場合にはデフォルト値の代わりにNULLを返します。
構文
引数
join_storage_table_name— 検索が行われる識別子。value_column— 必要なデータを含むテーブルのカラムの名前。join_keys— キーのリスト。
識別子はデフォルトのデータベース内で検索されます（設定ファイルの default_database を参照）。デフォルトのデータベースを上書きするには、USE db_nameを使用するか、データベースとテーブルを区切り文字 db_name.db_table を使用して指定します。
返される値
- キーのリストに対応する値のリストを返します。
特定のキーがソーステーブルに存在しない場合、そのキーに対してNULLが返されます。
例
入力テーブル:
クエリ:
結果:
catboostEvaluate
この関数はClickHouse Cloudでは利用できません。
外部のcatboostモデルを評価します。CatBoostは、Yandexによって開発された機械学習のためのオープンソースの勾配ブースティングライブラリです。 catboostモデルへのパスとモデル引数（特徴量）を受け取ります。Float64を返します。
構文
例
前提条件
- catboost評価ライブラリを構築する
catboostモデルを評価する前に、libcatboostmodel.<so|dylib>ライブラリを利用可能にする必要があります。CatBoost documentationでコンパイル方法を確認してください。
次に、libcatboostmodel.<so|dylib>へのパスをClickHouseの設定に指定します。
セキュリティと隔離の理由から、モデル評価はサーバープロセスではなく、clickhouse-library-bridgeプロセスで実行されます。
catboostEvaluate()が最初に実行されると、サーバーはライブラリブリッジプロセスを開始し、既に実行中でない場合は両プロセス経由でHTTPインターフェースを介して通信します。デフォルトでは、ポート9012が使用されます。他のサービスにポート9012が既に割り当てられている場合、異なるポートを以下のように指定できます。
- libcatboostを使用してcatboostモデルを訓練する
catboostモデルを訓練データセットから訓練する方法については、Training and applying modelsを参照してください。
throwIf
引数 x が真であれば、例外をスローします。
構文
引数
x- チェックする条件。message- カスタムエラーメッセージを提供する定数文字列。オプション。error_code- カスタムエラーコードを提供する定数整数。オプション。
error_code 引数を使用するには、設定パラメーター allow_custom_error_code_in_throwif を有効にする必要があります。
例
結果:
identity
引数を返します。デバッグやテスト用に設計されています。インデックスを使用する際のキャンセルを許可し、フルスキャンの問い合わせパフォーマンスを取得します。クエリがインデックスの使用の可能性を分析されるとき、アナライザーは identity 関数内のすべてを無視します。また、定数の折りたたみを無効にします。
構文
例
クエリ:
結果:
getSetting
現在のカスタム設定の値を返します。
構文
パラメータ
custom_setting— 設定名。String。
返される値
- 設定の現在の値。
例
結果:
参照
getSettingOrDefault
現在のカスタム設定の値を返す、またはカスタム設定が現在のプロファイルに設定されていなければ2番目の引数で指定されたデフォルト値を返します。
構文
パラメータ
custom_setting— 設定名。String。default_value— カスタム設定が設定されていない場合に返される値。値は任意のデータ型またはNULLである可能性があります。
返される値
- 設定の現在の値、または設定が設定されていない場合にはdefault_value。
例
結果:
参照
isDecimalOverflow
Decimal値がその精度の外にあるか、指定された精度の外にあるかをチェックします。
構文
引数
d— 値。Decimal。p— 精度。オプション。省略された場合、最初の引数の初期精度が使用されます。このパラメータは、データを別のデータベースやファイルから移行する際に役立ちます。UInt8。
返される値
1— Decimal値がその精度によって許可される以上の桁を持つ場合。0— Decimal値が指定された精度を満たしている場合。
例
クエリ:
結果:
countDigits
値を表すために必要な10進数の桁数を返します。
構文
引数
返される値
- 桁数。UInt8。
Decimal値はそのスケールを考慮に入れます: 基になる整数型を使って計算します（(value * scale)）。例えば: countDigits(42) = 2, countDigits(42.000) = 5, countDigits(0.04200) = 4。言い換えれば、countDecimal(x) > 18でDecimal64に対して10進数のオーバーフローを確認できます。これはisDecimalOverflowの遅いバージョンです。
例
クエリ:
結果:
errorCodeToName
- エラーコードのテキスト名。LowCardinality(String)。
構文
結果:
tcpPort
このサーバーがリッスンしているnative interfaceのTCPポート番号を返します。 分散テーブルのコンテキストで実行される場合、この関数は各シャードに関連する値を持つ通常のカラムを生成します。そうでない場合は定数値を生成します。
構文
引数
- なし。
返される値
- TCPポート番号。UInt16。
例
クエリ:
結果:
参照
currentProfiles
現在のユーザーの現在の設定プロファイルのリストを返します。
SET PROFILEコマンドを使用して、現在の設定プロファイルを変更できます。SET PROFILEコマンドが使用されなかった場合、この関数は現在のユーザーの定義（CREATE USERを参照）で指定されたプロファイルを返します。
構文
返される値
enabledProfiles
現在のユーザーに明示的および暗黙的に割り当てられた設定プロファイルを返します。明示的に割り当てられたプロファイルは、currentProfiles関数によって返されるプロファイルと同じです。暗黙的に割り当てられたプロファイルには、他の割り当てられたプロファイルの親プロファイル、付与されたロールを介して割り当てられたプロファイル、自身の設定を介して割り当てられたプロファイル、主要なデフォルトプロファイル（メインの設定ファイルの default_profile セクションを参照）を含みます。
構文
返される値
defaultProfiles
現在のユーザーの定義で指定されたすべてのプロファイルを返します（CREATE USERステートメントを参照）。
構文
返される値
currentRoles
現在のユーザーに割り当てられたロールを返します。ロールはSET ROLEステートメントによって変更できます。SET ROLEステートメントがなかった場合、currentRoles関数はdefaultRolesと同じ結果を返します。
構文
返される値
enabledRoles
現在のロールおよび、現在のロールに付与されたロールの名前を返します。
構文
返される値
defaultRoles
ユーザーがログインしたときにデフォルトで有効になるロールを返します。最初は、これらは現在のユーザーに付与されているすべてのロール（GRANTを参照）ですが、これはSET DEFAULT ROLEステートメントによって変更できます。
構文
返される値
getServerPort
サーバーポート番号を返します。ポートがサーバーによって使用されていない場合、例外がスローされます。
構文
引数
-
port_name— サーバーポートの名前。String。可能な値:- 'tcp_port'
- 'tcp_port_secure'
- 'http_port'
- 'https_port'
- 'interserver_http_port'
- 'interserver_https_port'
- 'mysql_port'
- 'postgresql_port'
- 'grpc_port'
- 'prometheus.port'
返される値
- サーバーポート番号。UInt16。
例
クエリ:
結果:
queryID
現在のクエリのIDを返します。他のクエリのパラメータはquery_idを介してsystem.query_logテーブルから抽出できます。
initialQueryID関数とは異なり、queryIDは異なるシャードで異なる結果を返すことがあります（例を参照）。
構文
返される値
- 現在のクエリのID。String
例
クエリ:
結果:
initialQueryID
初期の現在のクエリのIDを返します。他のクエリのパラメータはinitial_query_idを介してsystem.query_logテーブルから抽出できます。
queryID関数とは対照的に、initialQueryIDは異なるシャードで同じ結果を返します（例を参照）。
構文
返される値
- 初期の現在のクエリのID。String
例
クエリ:
結果:
initialQueryStartTime
初期の現在のクエリの開始時間を返します。
initialQueryStartTimeは異なるシャードで同じ結果を返します（例を参照）。
構文
返される値
- 初期の現在のクエリの開始時間。DateTime
例
クエリ:
結果:
partitionID
パーティションIDを計算します。
この関数は遅く、大量の行に対して呼び出してはいけません。
構文
引数
x— パーティションIDを返すカラム。y, ...— パーティションIDを返すための残りのNカラム（オプション）。
返される値
- 行が属するパーティションID。String。
例
クエリ:
結果:
shardNum
分散クエリでデータの一部を処理するシャードのインデックスを返します。インデックスは1から始まります。クエリが分散されていない場合は、定数値0が返されます。
構文
返される値
- シャードインデックスまたは定数
0。UInt32。
例
次の例では、2つのシャードを持つ構成が使用されています。クエリはsystem.oneテーブルで各シャードで実行されます。
クエリ:
結果:
参照
shardCount
分散クエリの総シャード数を返します。クエリが分散されていない場合は、定数値0が返されます。
構文
返される値
- 総シャード数または
0。UInt32。
参照
- shardNum()関数の例には、
shardCount()関数呼び出しも含まれています。
getOSKernelVersion
現在のOSカーネルのバージョンを含む文字列を返します。
構文
引数
- なし。
返される値
- 現在のOSカーネルのバージョン。String。
例
クエリ:
結果:
zookeeperSessionUptime
現在のZooKeeperセッションのアップタイムを秒単位で返します。
構文
引数
- なし。
返される値
- 現在のZooKeeperセッションのアップタイム（秒）。UInt32。
例
クエリ:
結果:
generateRandomStructure
ランダムなテーブル構造を生成します。フォーマットは column1_name column1_type, column2_name column2_type, ... です。
構文
引数
number_of_columns— 結果テーブル構造でのカラムの希望数。0またはNullに設定された場合、カラム数は1から128のランダムな値になります。デフォルト値:Null。seed- 安定した結果を生成するためのランダムシード。シードが指定されていない場合やNullに設定されている場合は、ランダムに生成されます。
すべての引数は定数でなければなりません。
返される値
- ランダムに生成されたテーブル構造。 String。
例
クエリ:
結果:
クエリ:
結果:
クエリ:
結果:
注意: 複雑なタイプ（Array、Tuple、Map、Nested）の最大ネスト深度は16に制限されています。
この関数は generateRandom と一緒に使用して、完全にランダムなテーブルを生成することができます。
structureToCapnProtoSchema
ClickHouseのテーブル構造をCapnProtoスキーマに変換します。
構文
引数
structure— フォーマットcolumn1_name column1_type, column2_name column2_type, ...のテーブル構造。root_struct_name— CapnProtoスキーマでのルート構造体の名前。デフォルト値 -Message。
返される値
- CapnProtoスキーマ。 String。
例
クエリ:
結果:
クエリ:
結果:
クエリ:
結果:
structureToProtobufSchema
ClickHouseのテーブル構造をProtobufスキーマに変換します。
構文
引数
structure— フォーマットcolumn1_name column1_type, column2_name column2_type, ...のテーブル構造。root_message_name— Protobufスキーマでのルートメッセージの名前。デフォルト値 -Message。
返される値
- Protobufスキーマ。 String。
例
クエリ:
結果:
クエリ:
結果:
クエリ:
結果:
formatQuery
指定されたSQLクエリのフォーマットされた可能性のある複数行版を返します。
クエリが正しく形成されていない場合、例外がスローされます。 NULL を返すには、関数 formatQueryOrNull() を使用することができます。
構文
引数
query- フォーマットされるSQLクエリ。 String
返される値
- フォーマットされたクエリ。 String。
例
結果:
formatQuerySingleLine
formatQuery() と似ていますが、返されるフォーマットされた文字列には改行が含まれません。
クエリが正しく形成されていない場合、例外がスローされます。 NULL を返すには、関数 formatQuerySingleLineOrNull() を使用することができます。
構文
引数
query- フォーマットされるSQLクエリ。 String
返される値
- フォーマットされたクエリ。 String。
例
結果:
variantElement
Variant カラムから指定した型のカラムを抽出します。
構文
引数
variant— Variant カラム。 Variant。type_name— 抽出するバリアントタイプの名前。 String。default_value- 指定した型のバリアントが存在しない場合に使用されるデフォルト値。任意の型が可能です。
返される値
- 指定した型の
Variantカラムのサブカラム。
例
variantType
Variant カラムの各行に対してバリアントタイプの名前を返します。行がNULLを含む場合は、その行に対して 'None' を返します。
構文
引数
variant— Variant カラム。 Variant。
返される値
- 各行のバリアントタイプ名を持つEnum8カラム。
例
minSampleSizeConversion
A/Bテストでの２つのサンプルのコンバージョン（割合）を比較するために必要な最小サンプルサイズを計算します。
構文
こちらの記事で説明されている式を使用します。処置群と対照群のサイズが同じと仮定します。返されるサンプルサイズは一つの群に対するもので、実験全体に必要なサンプルサイズは返される値の2倍になります。
引数
baseline— 基準コンバージョン。 Float。mde— 最小検出可能効果（MDE）（ポイント数として）。（例えば基準コンバージョン0.25に対して、MDEが0.03であるとき、期待される変化は 0.25 ± 0.03 です）。 Float。power— テストの必要な統計的パワー（1 - 第II種の誤りの確率）。 Float。alpha— テストの必要な有意水準（第I種の誤りの確率）。 Float。
返される値
3つの要素を持つ名前付き Tuple:
"minimum_sample_size"— 必要なサンプルサイズ。 Float64。"detect_range_lower"— 返された必要なサンプルサイズで検出できない値の範囲の下限（すなわち、"detect_range_lower"以下のすべての値は、指定されたalphaとpowerで検出可能）。baseline - mdeとして計算されます。 Float64。"detect_range_upper"— 返された必要なサンプルサイズで検出できない値の範囲の上限（すなわち、"detect_range_upper"以上のすべての値は、指定されたalphaとpowerで検出可能）。baseline + mdeとして計算されます。 Float64。
例
次のクエリは、基準コンバージョンが25%、MDEが3%、有意水準が5%、要求される統計的パワーが80%のA/Bテストに必要なサンプルサイズを計算します。
結果:
minSampleSizeContinuous
A/Bテストでの連続測定値の平均を比較するために必要な最小サンプルサイズを計算します。
構文
エイリアス: minSampleSizeContinous
こちらの記事で説明されている式を使用します。処置群と対照群のサイズが同じと仮定します。返されるサンプルサイズは一つの群に対するもので、実験全体に必要なサンプルサイズは返される値の2倍になります。また、処置群と対照群でテストメトリックの分散が等しいと仮定します。
引数
baseline— メトリックの基準値。 Integer または Float。sigma— メトリックの基準標準偏差。 Integer または Float。mde— 最小検出可能効果（MDE）（基準値の割合として）。（例えば基準値112.25に対して、MDEが0.03であるとき、期待される変化は112.25 ± 112.25*0.03です）。 Integer または Float。power— テストの必要な統計的パワー（1 - 第II種の誤りの確率）。 Integer または Float。alpha— テストの必要な有意水準（第I種の誤りの確率）。 Integer または Float。
返される値
3つの要素を持つ名前付き Tuple:
"minimum_sample_size"— 必要なサンプルサイズ。 Float64。"detect_range_lower"— 返された必要なサンプルサイズで検出できない値の範囲の下限（すなわち、"detect_range_lower"以下のすべての値は、指定されたalphaとpowerで検出可能）。baseline * (1 - mde)として計算されます。 Float64。"detect_range_upper"— 返された必要なサンプルサイズで検出できない値の範囲の上限（すなわち、"detect_range_upper"以上のすべての値は、指定されたalphaとpowerで検出可能）。baseline * (1 + mde)として計算されます。 Float64。
例
次のクエリは、基準値が112.25、標準偏差が21.1、MDEが3%、有意水準が5%、要求される統計的パワーが80%のメトリックに対するA/Bテストに必要なサンプルサイズを計算します。
結果:
connectionId
クライアントが現在のクエリを送信した接続IDを取得し、それをUInt64整数として返します。
構文
エイリアス: connection_id。
パラメータ
なし。
返される値
現在の接続ID。 UInt64。
実装の詳細
この関数は、デバッグシナリオやMySQLハンドラ内部での目的に最も有用です。MySQLの CONNECTION_ID 関数との互換性のために作られました。この関数は通常の生産クエリではあまり使用されません。
例
クエリ:
getClientHTTPHeader
HTTPヘッダーの値を取得します。
そのようなヘッダーが存在しない場合や、現在のリクエストがHTTPインターフェースを介して行われていない場合、この関数は空の文字列を返します。
特定のHTTPヘッダー（例えば、 Authentication と X-ClickHouse-*）は制限されています。
この関数は、設定 allow_get_client_http_header を有効にする必要があります。
この設定はデフォルトでは無効になっており、セキュリティ上の理由から、 Cookie のような一部のヘッダーは機密情報を含む可能性があります。
この関数では、HTTPヘッダーはケースセンシティブです。
この関数が分散クエリのコンテキストで使用された場合、返される結果は起動ノードのみが非空になります。
showCertificate
現在のサーバーのSSL（Secure Sockets Layer）証明書に関する情報を表示します。詳細は、Configuring SSL-TLSを参照してください。
構文
返される値
例
クエリ:
結果:
lowCardinalityIndices
LowCardinalityカラムの辞書における値の位置を返します。位置は1から始まります。LowCardinalityには各パーツごとの辞書があるため、この関数は異なるパーツで同じ値の異なる位置を返す場合があります。
構文
引数
col— ローカーダミナリティカラム。 LowCardinality。
返される値
- 現在のパーツの辞書における値の位置。 UInt64。
例
クエリ:
結果:
lowCardinalityKeys
LowCardinalityカラムの辞書の値を返します。ブロックが辞書サイズよりも小さい場合や大きい場合、結果は切り捨てられたり、デフォルト値で拡張されたりします。LowCardinalityには各パーツごとの辞書があるため、この関数は異なるパーツで異なる辞書値を返す場合があります。
構文
引数
col— ローカーダミナリティカラム。 LowCardinality。
返される値
- 辞書キー。 UInt64。
例
クエリ:
結果:
displayName
config (/operations/configuration-files) からの display_name の値を返します。設定されていない場合は、サーバの完全修飾ドメイン名（FQDN）が返されます。
構文
返される値
- configからの
display_nameの値、または設定されていない場合はサーバのFQDN。 String。
例
display_name は config.xml に設定できます。例えば、display_name が 'production' に設定されたサーバを考えてみましょう。
クエリ:
結果:
transactionID
transactionのIDを返します。
この関数は実験的な機能セットの一部です。以下の設定を構成に追加して実験的なトランザクションサポートを有効にしてください:
詳しい情報は、Transactional (ACID) supportのページを参照してください。
構文
返される値
-
start_csn、local_tid、およびhost_idで構成されるタプルを返します。 Tuple。 -
start_csn: グローバルな順序番号、トランザクションが開始したときに見られた最新のコミットタイムスタンプ。 UInt64。 -
local_tid: 特定のstart_csn内でこのホストによって開始された各トランザクションのためにユニークなローカル順序番号。 UInt64。 -
host_id: このトランザクションを開始したホストのUUID。 UUID。
例
クエリ:
結果:
transactionLatestSnapshot
読み取り可能なtransactionの最新スナップショット（コミットシーケンス番号）を返します。
この関数は実験的な機能セットの一部です。以下の設定を構成に追加して実験的なトランザクションサポートを有効にしてください:
詳しい情報は、Transactional (ACID) supportのページを参照してください。
構文
返される値
- トランザクションの最新スナップショット（CSN）を返します。 UInt64
例
クエリ:
結果:
transactionOldestSnapshot
現在実行中のtransactionに対して可視の最も古いスナップショット（コミットシーケンス番号）を返します。
この関数は実験的な機能セットの一部です。以下の設定を構成に追加して実験的なトランザクションサポートを有効にしてください:
詳しい情報は、Transactional (ACID) supportのページを参照してください。
構文
返される値
- トランザクションの最も古いスナップショット（CSN）を返します。 UInt64
例
クエリ:
結果:
getSubcolumn
テーブル式または識別子とサブカラム名を持つ定数文字列を取り、要求されたサブカラムを式から抽出して返します。
構文
引数
col_name— テーブル式または識別子。 Expression, Identifier。subcol_name— サブカラムの名前。 String。
返される値
- 抽出されたサブカラムを返します。
例
クエリ:
結果:
getTypeSerializationStreams
データ型のストリームパスを列挙します。
この関数は開発者用に意図されています。
構文
引数
col— データ型のカラムまたは文字列表現で、データ型が検出されます。
返される値
例
クエリ:
結果:
クエリ:
結果:
globalVariable
定数文字列引数を取り、その名前のグローバル変数の値を返します。この関数はMySQLとの互換性のために意図されており、ClickHouseの通常の操作には必要ありません。定義されているダミーのグローバル変数はわずかです。
構文
引数
name— グローバル変数の名前。 String。
返される値
- 変数
nameの値を返します。
例
クエリ:
結果:
getMaxTableNameLengthForDatabase
指定されたデータベースでの最大テーブル名の長さを返します。
構文
引数
database_name— 指定されたデータベースの名前。 String。
返される値
- 最大テーブル名の長さを返します。
例
クエリ:
結果: