thevar1able/ClickHouse
1
0
Fork 0
mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-14 18:32:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
9172d572c6
ClickHouse/docs/ja/integrations/data-visualization/grafana/query-builder.md
Miki Matsumoto 1e15312729 add translated Japanese docs
2024-11-18 11:58:58 +09:00

23 KiB
Raw Blame History

sidebar_label sidebar_position slug description
クエリビルダー 2 /ja/integrations/grafana/query-builder ClickHouse Grafana プラグインでのクエリビルダーの使用

クエリビルダー

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

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

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

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

クエリタイプ

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

Table

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

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

<img src={require('./images/demo_table_query.png').default} class="image" alt="Example aggregate table query" />

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

Logs

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

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

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

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

<img src={require('./images/demo_logs_query.png').default} class="image" alt="Example OTel logs query" />


このクエリタイプは、上部にログヒストグラムパネルとともに、ログパネルとしてデータをレンダリングします。

クエリ内で選択された追加カラムは、展開されたログ行内で確認できます： <img src={require('./images/demo_logs_query_fields.png').default} class="image" alt="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 By GROUP BY 式のリスト。集計モードでのみ表示されます。
Order By ORDER BY 式のリスト。
Limit クエリの末尾に LIMIT 文を追加します。0 に設定すると除外されますが、時系列データセットではフルビジュアライゼーションを表示するために推奨されます。
フィルター WHERE 句に適用されるフィルターのリスト。

<img src={require('./images/demo_time_series_query.png').default} class="image" alt="Example time series query" />

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

Traces

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

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

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

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

<img src={require('./images/demo_trace_query.png').default} class="image" alt="Example OTel trace query" />

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

SQL エディタ

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

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

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

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

<img src={require('./images/demo_raw_sql_query.png').default} class="image" alt="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)
$__fromTime Grafana パネルの範囲の開始時刻をDateTimeとしてキャストしたものに置き換えます。 toDateTime(1415792726)
$__fromTime_ms パネル範囲の開始時刻をDateTime64としてキャストしたものに置き換えます。 fromUnixTimestamp64Milli(1415792726123)
$__toTime Grafana パネル範囲の終了時刻を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