Skip to main content
Edit this page

クエリビルダー

任意のクエリは ClickHouse プラグインで実行できます。 クエリビルダーはシンプルなクエリには便利なオプションですが、複雑なクエリには SQL エディタを使用する必要があります。

クエリビルダー内のすべてのクエリにはクエリタイプがあり、少なくとも1つのカラムを選択する必要があります。

使用可能なクエリタイプは次のとおりです：

  • Table: データを表形式で表示するための最も簡単なクエリタイプ。集計関数を含む単純なクエリにも複雑なクエリにも適しています。
  • Logs: ログのクエリ作成に最適化されています。デフォルト設定されたエクスプローラビューで最適に機能します。
  • Time Series: 時系列クエリの作成に最適です。専用の時間カラムを選択し、集計関数を追加できます。
  • Traces: トレースの検索/表示に最適化されています。デフォルト設定されたエクスプローラビューで最適に機能します。
  • SQL Editor: クエリの完全な制御を行いたい場合に使用できます。このモードでは任意の SQL クエリを実行できます。

クエリタイプ​

クエリタイプ設定は、作成中のクエリのタイプに合うようにクエリビルダーのレイアウトを変更します。 クエリタイプは、データの可視化に使用されるパネルも決定します。

Table​

最も柔軟なクエリタイプは Table クエリです。これは、単純および集計クエリを処理するために設計された他のクエリビルダーを包括します。

フィールド説明
ビルダーモード単純なクエリは集計や Group By を含まず、集計クエリはこれらのオプションを含みます。
カラム選択されたカラム。このフィールドに生の SQL を入力して、関数やカラムのエイリアシングを許可します。
集計集計関数のリスト。関数とカラムのカスタム値を許可します。集計モードでのみ表示されます。
Group ByGROUP BY 式のリスト。集計モードでのみ表示されます。
Order ByORDER BY 式のリスト。
Limitクエリの末尾に LIMIT 文を追加します。0 に設定すると除外されます。一部の可視化では、すべてのデータを表示するために 0 に設定する必要があります。
フィルターWHERE 句に適用されるフィルターのリスト。
Example aggregate table query

このクエリタイプは、データをテーブルとしてレンダリングします。

Logs​

Logs クエリタイプは、ログデータのクエリ作成に焦点を当てたクエリビルダーを提供します。 デフォルトはデータソースのログ設定で設定することができ、クエリビルダーをデフォルトのデータベース/テーブルとカラムでプレロードできます。 また、OpenTelemetry を有効にして、スキーマバージョンに応じたカラムを自動選択することもできます。

時間とレベルフィルターがデフォルトで追加され、時間カラムの Order By も含まれます。 これらのフィルターは各フィールドに関連付けられており、カラムが変更されると更新されます。 レベルフィルターはデフォルトでは SQL から除外されており、IS ANYTHING オプションから変更することで有効になります。

Logs クエリタイプはデータリンクをサポートしています。

フィールド説明
Use OTelOpenTelemetry カラムを有効にします。選択された OTel スキーマバージョンで定義されたカラムを使用するように選択されたカラムを上書きします（カラム選択を無効にします）。
カラムログ行に追加されるカラム。生の SQL をこのフィールドに入力して関数やカラムのエイリアシングを許可します。
時間ログのプライマリタイムスタンプカラム。時間的な型を表示しますが、カスタム値/関数も許可されます。
ログレベル任意。ログのレベルまたは重大度。通常はINFO, error, Debugなどの値が使用されます。
メッセージログメッセージの内容。
Order ByORDER BY 式のリスト。
Limitクエリの末尾に LIMIT 文を追加します。0 に設定すると除外されますが、大規模なログデータセットには推奨されません。
フィルターWHERE 句に適用されるフィルターのリスト。
メッセージフィルターLIKE %value% を使用してログを便利にフィルターリングするためのテキスト入力。入力が空の場合は除外されます。
Example OTel logs query
このクエリタイプは、上部にログヒストグラムパネルとともに、ログパネルとしてデータをレンダリングします。

クエリ内で選択された追加カラムは、展開されたログ行内で確認できます：

Example of extra fields on logs query

Time Series​

Time Series クエリタイプはtableに似ていますが、時系列データに焦点を当てています。

2つのビューはほぼ同じですが、以下の重要な違いがあります：

  • 専用の時間フィールド。
  • 集計モードでは、時間間隔マクロが自動的に適用され、Time フィールドに対する Group By が追加されます。
  • 集計モードでは、「カラム」フィールドが非表示になります。
  • 時間範囲フィルターと Order By が Time フィールドに自動的に追加されます。

:::重要 あなたのビジュアライゼーションがデータを欠いている場合 場合によっては、時系列パネルが LIMIT がデフォルトで 1000 に設定されているために切り捨てられたように表示されることがあります。

データセットが許せば、LIMIT 条項を削除して 0 に設定してみてください。 :::

フィールド説明
ビルダーモード単純なクエリは集計および Group By を含まず、集計クエリはこれらのオプションを含みます。
時間クエリのプライマリ時間カラム。時間的な型を表示しますが、カスタム値/関数も許可されます。
カラム選択されたカラム。このフィールドに生の SQL を入力して、関数やカラムのエイリアシングを許可します。単純モードでのみ表示されます。
集計集計関数のリスト。関数とカラムのカスタム値を許可します。集計モードでのみ表示されます。
Group ByGROUP BY 式のリスト。集計モードでのみ表示されます。
Order ByORDER BY 式のリスト。
Limitクエリの末尾に LIMIT 文を追加します。0 に設定すると除外されますが、時系列データセットではフルビジュアライゼーションを表示するために推奨されます。
フィルターWHERE 句に適用されるフィルターのリスト。
Example time series query

このクエリタイプは、時系列パネルでデータをレンダリングします。

Traces​

Traces クエリタイプは、トレースを簡単に検索および表示するためのクエリビルダーを提供します。 これは OpenTelemetry データ用に設計されていますが、別のスキーマからトレースをレンダリングするためにカラムを選択することもできます。 デフォルトはデータソースのトレース設定で設定することができ、クエリビルダーをデフォルトのデータベース/テーブルとカラムでプレロードできます。デフォルトが設定されている場合、カラム選択はデフォルトで折りたたまれます。 また、OpenTelemetry を有効にして、スキーマバージョンに応じたカラムを自動選択することもできます。

デフォルトのフィルターは、トップレベルのスパンのみを表示する意図で追加されています。 Time および Duration Time の Order By も含まれています。 これらのフィルターは各フィールドに関連付けられており、カラムが変更されると更新されます。 サービス名フィルターはデフォルトでは SQL から除外されており、IS ANYTHING オプションから変更することで有効になります。

Traces クエリタイプはデータリンクをサポートしています。

フィールド説明
Trace モードクエリを Trace Search から Trace ID 検索に変更します。
Use OTelOpenTelemetry カラムを有効にします。選択された OTel スキーマバージョンで定義されたカラムを使用するように選択されたカラムを上書きします（カラム選択を無効にします）。
Trace ID カラムトレースの ID。
Span ID カラムスパン ID。
Parent Span ID カラム親スパン ID。これは通常、トップレベルトレースでは空です。
サービス名カラムサービス名。
操作名カラム操作名。
開始時間カラムトレーススパンのプライマリ時間カラム。スパンが開始された時刻。
期間時間カラムスパンの期間。Grafana はデフォルトでこれをミリ秒の浮動小数点数で期待しています。変換はDuration Unitドロップダウンを介して自動的に適用されます。
期間単位期間に使用される時間の単位。デフォルトではナノ秒。選択された単位は、Grafana に必要なミリ秒の浮動小数点数に変換されます。
タグカラムスパンタグ。OTel に基づくスキーマを使用していない場合は除外します。特定のマップカラムタイプを期待します。
サービスタグカラムサービスタグ。OTel に基づくスキーマを使用していない場合は除外します。特定のマップカラムタイプを期待します。
Order ByORDER BY 式のリスト。
Limitクエリの末尾に LIMIT 文を追加します。0 に設定すると除外されますが、大規模なトレースデータセットには推奨されません。
フィルターWHERE 句に適用されるフィルターのリスト。
Trace IDフィルターで使用するトレース ID。Trace ID モードでのみ使用され、Trace ID データリンクを開くときに使用されます。
Example OTel trace query

このクエリタイプは、Trace Search モードではテーブルビューで、Trace ID モードではトレースパネルでデータをレンダリングします。

SQL エディタ​

クエリビルダーには複雑すぎるクエリの場合は、SQL エディタを使用できます。 これにより、生の ClickHouse SQL を記述して実行することでクエリを完全に制御できます。

SQL エディタは、クエリエディタの上部で「SQL Editor」を選択することで開くことができます。

このモードでもマクロ関数を使用できます。

クエリタイプを切り替えて、クエリに最も適したビジュアライゼーションを取得できます。 ダッシュボードビュー、特に時系列データでは、この切り替えも効果があります。

Example raw SQL query

データリンク​

Grafana データリンク は新しいクエリへのリンクを作成するために使用できます。 この機能は、ClickHouse プラグイン内でトレースをログにリンクしたりその逆を実行したりするために有効化されています。 データソースの設定で OpenTelemetry を両方のログとトレースに設定すると最適に機能します。

テーブル内のトレースリンクの例Trace links in table
ログ内のトレースリンクの例Trace links in logs

データリンクの作成方法​

あなたは、クエリ内でtraceIDという名前のカラムを選択することでデータリンクを作成できます。この名前は大文字と小文字を区別せず、"ID"の前にアンダースコアを追加することもサポートしています。例えば、traceId, TraceId, TRACE_ID, tracE_iDはすべて有効です。

OpenTelemetry がログまたはトレースクエリで有効になっている場合、トレース ID カラムは自動的に含まれます。

トレース ID カラムを含めることで、「View Trace」および「View Logs」リンクがデータに添付されます。

リンクの機能​

データリンクが存在すると、提供されたトレース ID を使用してトレースおよびログを開くことができます。

「View Trace」はトレース付きの分割パネルを開き、「View Logs」はトレース ID でフィルタリングされたログクエリを開きます。 リンクがダッシュボードではなくエクスプローラビューからクリックされた場合、リンクはエクスプローラビューの新しいタブで開かれます。

ログとトレースの両方に対してデフォルトが構成されていることが、クエリタイプを跨ぐ（ログからトレース、トレースからログ）のに必要です。同じクエリタイプのリンクを開く場合には、ただクエリをコピーすることで済むため、デフォルトは必要ありません。

ログクエリ（左パネル）からトレースを表示する例（右パネル）Example of data links linking

マクロ​

マクロはクエリに動的 SQL を追加する簡単な方法です。 クエリが ClickHouse サーバーに送信される前に、プラグインはマクロを展開し、完全な式に置き換えます。

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 カラムに適用されています。

プラグインは中括弧 {} を使用した表記もサポートしています。クエリが パラメーター内に必要な場合は、この表記を使用します。

マクロのリスト​

プラグインで利用可能なすべてのマクロのリストです：

マクロ説明出力例
$__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)$__dateFilter() と $__timeFilter() を別々の Date と DateTime カラムで組み合わせたショートハンドです。Alias $__dt()$__dateFilter(dateColumn) AND $__timeFilter(timeColumn)
$__fromTimeGrafana パネルの範囲の開始時刻をDateTimeとしてキャストしたものに置き換えます。toDateTime(1415792726)
$__fromTime_msパネル範囲の開始時刻をDateTime64としてキャストしたものに置き換えます。fromUnixTimestamp64Milli(1415792726123)
$__toTimeGrafana パネル範囲の終了時刻をDateTimeとしてキャストしたものに置き換えます。toDateTime(1447328726)
$__toTime_msパネル範囲の終了時刻をDateTime64としてキャストしたものに置き換えます。fromUnixTimestamp64Milli(1447328726456)
$__timeInterval(columnName)ウィンドウサイズに基づく間隔を計算する関数で置き換えます。toStartOfInterval(toDateTime(columnName), INTERVAL 20 second)
$__timeInterval_ms(columnName)ウィンドウサイズに基づく間隔を計算する関数で置き換えます（ミリ秒単位）。toStartOfInterval(toDateTime64(columnName, 3), INTERVAL 20 millisecond)
$__interval_sダッシュボード間隔を秒単位で置き換えます。20
$__conditionalAll(condition, $templateVar)テンプレート変数がすべての値を選択していない場合は第一引数に置き換えます。テンプレート変数がすべての値を選択する場合は 1=1 に置き換えます。condition または 1=1