クエリビルダー - ClickHouse Documentation

ClickHouse プラグインでは、あらゆるクエリを実行できます。単純なクエリにはクエリビルダーが便利ですが、複雑なクエリでは SQL エディタを使用する必要があります。クエリビルダー内のすべてのクエリにはクエリタイプがあり、少なくとも 1 つのカラムを選択する必要があります。利用可能なクエリタイプは次のとおりです。

Table: データをテーブル形式で表示するための、最もシンプルなクエリタイプです。集計関数を含む単純なクエリにも複雑なクエリにも、汎用的に適しています。
Logs: ログ用のクエリ作成に最適化されています。デフォルトを設定した Explore ビューで最も効果を発揮します。
Time Series: 時系列クエリの作成に最適です。専用の時刻カラムを選択し、集計関数を追加できます。
Traces: トレースの検索や表示に最適化されています。デフォルトを設定した Explore ビューで最も効果を発揮します。
SQL Editor: クエリを完全に制御したい場合は SQL エディタを使用できます。このモードでは、あらゆる SQL クエリを実行できます。

クエリタイプ

クエリタイプ設定を変更すると、作成するクエリの種類に合わせてクエリビルダーのレイアウトが変わります。また、クエリタイプによって、データの可視化に使用するパネルも決まります。

テーブル

最も柔軟なクエリタイプは、テーブルクエリです。これは、シンプルなクエリや集約クエリを扱うために設計された、ほかのクエリビルダー全般を包括するクエリタイプです。

フィールド	説明
ビルダーモード	シンプルクエリでは Aggregates と Group By は含まれず、集約クエリではこれらのオプションが含まれます。
カラム	選択したカラムです。関数やカラムの別名を使えるように、このフィールドには生の SQL を入力できます。
Aggregates	集約関数の一覧です。関数とカラムにカスタム値を設定できます。集計モードでのみ表示されます。
Group By	GROUP BY 式の一覧です。集計モードでのみ表示されます。
Order By	ORDER BY 式の一覧です。
Limit	クエリの末尾に LIMIT ステートメントを追加します。`0` に設定すると追加されません。すべてのデータを表示するには、一部の可視化でこれを `0` に設定する必要がある場合があります。
Filters	`WHERE` 句に適用するフィルターの一覧です。

このクエリタイプでは、データがテーブルとして表示されます。

ログ

ログのクエリタイプでは、ログデータのクエリに特化したクエリビルダーを利用できます。クエリビルダーでデフォルトのデータベース/テーブルやカラムをあらかじめ読み込めるように、デフォルト値はデータソースのログ設定で構成できます。また、OpenTelemetry を有効にすると、スキーマバージョンに応じてカラムを自動選択できます。 Time と Level のフィルターはデフォルトで追加され、さらに Time カラムに対する ORDER BY も追加されます。これらのフィルターはそれぞれ対応するフィールドに関連付けられており、カラムが変更されると更新されます。 Level フィルターはデフォルトでは SQL に含まれず、IS ANYTHING オプションから変更すると有効になります。ログのクエリタイプはデータリンクをサポートしています。

フィールド	説明
Use OTel	OpenTelemetry のカラムを有効にします。選択した OTel スキーマバージョンで定義されたカラムを使用するように、選択中のカラムを上書きします (カラム選択は無効になります) 。
カラム	ログの行に追加する追加カラムです。関数やカラムのエイリアスを使用できるよう、このフィールドには生の SQL を入力できます。
Time	ログのプライマリタイムスタンプカラムです。時刻系の型が表示されますが、カスタム値や関数も使用できます。
Log Level	任意。ログの level または severity です。値は通常、`INFO`、`error`、`Debug` などになります。
Message	ログメッセージの内容です。
Order By	ORDER BY 式の一覧です。
Limit	クエリの末尾に LIMIT ステートメントを追加します。`0` に設定すると除外されますが、大規模なログデータセットでは推奨されません。
Filters	`WHERE` 句に適用するフィルターの一覧です。
Message Filter	`LIKE %value%` を使ってログを簡単に絞り込むためのテキスト入力です。入力が空の場合は除外されます。

このクエリタイプでは、データはログパネルに表示され、上部にはログヒストグラムパネルも表示されます。クエリで選択した追加カラムは、展開したログの行で確認できます。

時系列

時系列クエリタイプは、table と似ていますが、時系列データに重点を置いています。この 2 つのビューはほぼ同じですが、主な違いは次のとおりです。

専用の Time フィールドがあります。
集計モードでは、Time フィールドに対する Group By とあわせて、時間間隔マクロが自動的に適用されます。
集計モードでは、“カラム” フィールドは表示されません。
Time フィールドに対して、時間範囲フィルターと Order By が自動的に追加されます。

可視化にデータが表示されていませんか？状況によっては、limit のデフォルト値が 1000 のため、時系列パネルが途中で切れているように見えることがあります。LIMIT 句を 0 に設定して削除してみてください (データセットで許可されている場合) 。

Field	Description
ビルダーモード	シンプルクエリでは Aggregates と Group By は含まれず、集計クエリではこれらのオプションが含まれます。
Time	クエリのプライマリ時間カラムです。時刻型に相当する型が表示されますが、カスタム値や関数も指定できます。
カラム	選択したカラムです。関数やカラムのエイリアスを使用できるように、このフィールドには生の SQL を入力できます。シンプルモードでのみ表示されます。
Aggregates	aggregate functions の一覧です。関数とカラムにはカスタム値を指定できます。集計モードでのみ表示されます。
Group By	GROUP BY 式の一覧です。集計モードでのみ表示されます。
Order By	ORDER BY 式の一覧です。
Limit	クエリの末尾に LIMIT ステートメントを追加します。`0` に設定すると追加されません。可視化全体を表示するため、一部の時系列データセットではこの設定を推奨します。
Filters	`WHERE` 句に適用するフィルターの一覧です。

このクエリタイプでは、データが時系列パネルで表示されます。

トレース

トレースクエリタイプには、トレースを簡単に検索して表示できるクエリビルダーが用意されています。これは OpenTelemetry データ向けに設計されていますが、別のスキーマのトレースを表示するためにカラムを選択することもできます。デフォルトはデータソースのトレース設定で設定でき、クエリビルダーにデフォルトのデータベース/テーブルとカラムを事前に読み込ませることができます。デフォルトが設定されている場合、カラム選択は既定で折りたたまれます。また、OpenTelemetry を有効にすると、スキーマバージョンに応じてカラムを自動選択できます。既定のフィルターは、トップレベルの span のみを表示する目的で追加されています。また、Time カラムと Duration Time カラムに対する ORDER BY も含まれています。これらのフィルターはそれぞれ対応するフィールドに紐付いており、カラムを変更すると更新されます。 Service Name フィルターは既定では SQL に含まれず、IS ANYTHING オプションから変更した場合に有効になります。トレースクエリタイプはデータリンクをサポートしています。

フィールド	説明
Trace Mode	クエリを Trace Search から Trace ID ルックアップに切り替えます。
Use OTel	OpenTelemetry カラムを有効にします。選択した OTel スキーマバージョンで定義されたカラムを使用するよう、現在選択されているカラムを上書きします (カラム選択は無効になります) 。
Trace ID Column	trace の ID。
Span ID Column	Span ID。
Parent Span ID Column	親 span ID。通常、トップレベルのトレースでは空です。
Service Name Column	サービス名。
Operation Name Column	オペレーション名。
Start Time Column	trace span のプライマリ time カラム。span の開始時刻です。
Duration Time Column	span の継続時間。既定では Grafana はこれをミリ秒の float として想定します。`Duration Unit` ドロップダウンにより、自動的に変換されます。
Duration Unit	継続時間に使用する時間単位。既定ではナノ秒です。選択した単位は、Grafana が必要とするミリ秒の float に変換されます。
Tags Column	Span タグ。特定の Map カラム型を前提としているため、OTel ベースのスキーマを使用しない場合は除外してください。
Service Tags Column	サービスタグ。特定の Map カラム型を前提としているため、OTel ベースのスキーマを使用しない場合は除外してください。
Order By	ORDER BY 式の一覧。
Limit	クエリの末尾に LIMIT ステートメントを追加します。`0` に設定すると除外されますが、大規模なトレースデータセットでは推奨されません。
Filters	`WHERE` 句に適用するフィルターの一覧。
Trace ID	フィルター対象の Trace ID。Trace ID モードの場合、および trace ID のデータリンクを開く場合にのみ使用されます。

このクエリタイプでは、Trace Search モードではデータがテーブルビューで表示され、Trace ID モードではトレースパネルで表示されます。

SQL エディタ

クエリビルダーでは対応できないような複雑なクエリには、SQL エディタを使用できます。プレーンな ClickHouse SQL を記述して実行できるため、クエリを完全に制御できます。 SQL エディタは、クエリエディタ上部の “SQL Editor” を選択すると開けます。このモードでもマクロ関数を引き続き使用できます。クエリに最適な可視化を表示するために、クエリタイプを切り替えることもできます。この切り替えはダッシュボード表示にも影響し、特に時系列データで顕著です。

データリンク

Grafana の data links を使うと、新しいクエリへリンクできます。この機能は、トレースからログへ、またログからトレースへリンクできるように、ClickHouse プラグインで有効化されています。最も効果的に利用するには、data source’s config でログとトレースの両方に対して OpenTelemetry を設定してください。

テーブル内のトレースリンクの例

ログ内のトレースリンクの例

データリンクを作成する方法

クエリで traceID という名前のカラムを選択すると、データリンクを作成できます。この名前は大文字と小文字を区別せず、“ID” の前にアンダースコアを付けた形式にも対応しています。たとえば、traceId、TraceId、TRACE_ID、tracE_iD はいずれも有効です。ログまたはトレースのクエリで OpenTelemetry が有効になっている場合、トレース ID カラムが自動的に含まれます。トレース ID カラムを含めると、データに「View Trace」および「View Logs」のリンクが追加されます。

リンク機能

データリンクがあると、指定された trace ID を使ってトレースとログを開けます。 “View Trace” をクリックすると、trace を表示する分割パネルが開きます。“View Logs” をクリックすると、trace ID で絞り込まれたログクエリが開きます。 Explore ビューではなくダッシュボードからリンクをクリックした場合、そのリンクは Explore ビューの新しいタブで開きます。クエリタイプをまたぐ場合 (ログからトレース、トレースからログ) は、ログとトレースの両方でデフォルトを設定しておく必要があります。同じクエリタイプのリンクを開く場合は、クエリをそのままコピーできるため、デフォルトは不要です。

ログクエリ (左パネル) から trace (右パネル) を表示する例

マクロ

マクロは、クエリに動的な SQL を追加するためのシンプルな方法です。クエリが ClickHouse server に送信される前に、プラグインがマクロを展開して完全な式に置き換えます。 SQL エディタとクエリビルダーのどちらのクエリでも、マクロを使用できます。

マクロの使用

マクロはクエリ内のどこでも使用でき、必要に応じて複数回指定できます。 $__timeFilter マクロの使用例を以下に示します。入力:

SELECT log_time, log_message
FROM logs
WHERE $__timeFilter(log_time)

最終的なクエリの出力:

SELECT log_time, log_message
FROM logs
WHERE log_time >= toDateTime(1415792726) AND log_time <= toDateTime(1447328726)

この例では、Grafana ダッシュボードの時間範囲が log_time カラムに適用されます。このプラグインは、中括弧 {} を使う記法にも対応しています。parameters 内でクエリが必要な場合は、この記法を使用してください。

マクロの一覧

これは、プラグインで使用できるすべてのマクロの一覧です。

Macro	Description	Output example
`$__dateFilter(columnName)`	Grafana パネルの時間範囲を使って、指定したカラムに対する時間範囲フィルターに置き換えられます。Date を使用します。	`columnName >= toDate('2022-10-21') AND columnName <= toDate('2022-10-23')`
`$__timeFilter(columnName)`	Grafana パネルの時間範囲を使って、指定したカラムに対する時間範囲フィルターに置き換えられます。DateTime を使用します。	`columnName >= toDateTime(1415792726) AND time <= toDateTime(1447328726)`
`$__timeFilter_ms(columnName)`	Grafana パネルの時間範囲を使って、指定したカラムに対する時間範囲フィルターに置き換えられます。DateTime64 を使用します。	`columnName >= fromUnixTimestamp64Milli(1415792726123) AND columnName <= fromUnixTimestamp64Milli(1447328726456)`
`$__dateTimeFilter(dateColumn, timeColumn)`	個別の Date カラムと DateTime カラムを使って `$__dateFilter()` と `$__timeFilter()` を組み合わせる短縮記法です。エイリアスは `$__dt()` です。	`$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)`
`$__fromTime`	Grafana パネルの時間範囲の開始時刻を DateTime にキャストした値に置き換えられます。	`toDateTime(1415792726)`
`$__fromTime_ms`	パネルの時間範囲の開始時刻を DateTime64 にキャストした値に置き換えられます。	`fromUnixTimestamp64Milli(1415792726123)`
`$__toTime`	Grafana パネルの時間範囲の終了時刻を DateTime にキャストした値に置き換えられます。	`toDateTime(1447328726)`
`$__toTime_ms`	パネルの時間範囲の終了時刻を DateTime64 にキャストした値に置き換えられます。	`fromUnixTimestamp64Milli(1447328726456)`
`$__timeInterval(columnName)`	秒単位のウィンドウサイズに基づいて interval を計算する関数に置き換えられます。	`toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)`
`$__timeInterval_ms(columnName)`	ミリ秒単位のウィンドウサイズに基づいて interval を計算する関数に置き換えられます。	`toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)`
`$__interval_s`	ダッシュボードの interval (秒単位) に置き換えられます。	`20`
`$__conditionalAll(condition, $templateVar)`	2 番目のパラメーターで指定したテンプレート変数ですべての値が選択されていない場合は、最初のパラメーターに置き換えられます。テンプレート変数ですべての値が選択されている場合は、1=1 に置き換えられます。	`condition` or `1=1`

​クエリタイプ

​テーブル

​ログ

​時系列

​トレース

​SQL エディタ

​データリンク

​データリンクを作成する方法

​リンク機能

​マクロ

​マクロの使用

​マクロの一覧

クエリタイプ

テーブル

ログ

時系列

トレース

SQL エディタ

データリンク

データリンクを作成する方法

リンク機能

マクロ

マクロの使用

マクロの一覧