SQLベースの可視化

ClickStack は、生の SQL クエリに基づく可視化をサポートしています。これにより、ダッシュボードレベルの時間範囲、フィルター、チャートの描画と連携しながら、クエリロジックを完全に制御できます。 SQL ベースの可視化は、組み込みの Chart Explorer では対応しきれないことを行いたい場合に有用です。たとえば、テーブルを結合したり、chart builder ではサポートされていない複雑な集計を作成したりする場合です。

SQL ベースの可視化の作成

SQL ベースの可視化を作成するには、ダッシュボードのタイルエディタを開き、SQL タブを選択します。その後、次の手順で進めます。

クエリの実行先となる ClickHouse 接続 を選択します。
必要に応じて ログソース を選択します。これにより、$__filters マクロを介してダッシュボードレベルのフィルタをグラフに適用できるようになります。
エディタで SQL クエリを記述し、クエリパラメータとマクロを使ってダッシュボードの時間範囲やフィルタと連携させます。
play ボタンをクリックして結果をプレビューし、Save をクリックします。

クエリパラメータ

クエリパラメータを使用すると、SQL からダッシュボードの現在の時間範囲と粒度を参照できます。構文には、ClickHouse のパラメータ化クエリ構文 {paramName:Type} を使用します。

利用可能なパラメータ

使用できるパラメータは、チャートの種類によって異なります。 折れ線グラフチャートおよび積み上げ棒グラフチャート:

パラメータ	型	説明
`{startDateMilliseconds:Int64}`	Int64	ダッシュボードの日付範囲の開始 (エポックからのミリ秒)
`{endDateMilliseconds:Int64}`	Int64	ダッシュボードの日付範囲の終了 (エポックからのミリ秒)
`{intervalSeconds:Int64}`	Int64	時間バケットのサイズ (粒度に基づく、秒単位)
`{intervalMilliseconds:Int64}`	Int64	時間バケットのサイズ (粒度に基づく、ミリ秒単位)

Table、Pie、および Number チャート:

パラメータ	型	説明
`{startDateMilliseconds:Int64}`	Int64	ダッシュボードの日付範囲の開始 (エポックからのミリ秒)
`{endDateMilliseconds:Int64}`	Int64	ダッシュボードの日付範囲の終了 (エポックからのミリ秒)

マクロ

マクロは、よく使われる ClickHouse SQL の式に展開されるショートカットです。$__ というプレフィックスが付き、クエリが ClickHouse に送信される前に置換されます。

時間境界マクロ

これらのマクロは、ダッシュボードの開始時刻または終了時刻を表す ClickHouse の式を返します。引数はありません。

Macro	Expands to	Column type
`$__fromTime`	`toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))`	DateTime
`$__toTime`	`toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))`	DateTime
`$__fromTime_ms`	`fromUnixTimestamp64Milli({startDateMilliseconds:Int64})`	DateTime64
`$__toTime_ms`	`fromUnixTimestamp64Milli({endDateMilliseconds:Int64})`	DateTime64
`$__interval_s`	`{intervalSeconds:Int64}`	Int64

時間フィルターマクロ

これらのマクロは、カラムをダッシュボードの時間範囲で絞り込む WHERE 句のフラグメントを生成します。

Macro	Description
`$__timeFilter(column)`	`DateTime` カラムをダッシュボードの時間範囲で絞り込みます
`$__timeFilter_ms(column)`	`DateTime64` (ミリ秒) カラムをダッシュボードの時間範囲で絞り込みます
`$__dateFilter(column)`	`Date` カラムをダッシュボードの時間範囲で絞り込みます
`$__dateTimeFilter(dateCol, timeCol)`	個別の `Date` カラムと `DateTime` カラムを使って絞り込みます
`$__dt(dateCol, timeCol)`	`$__dateTimeFilter` のエイリアス

$__timeFilter(TimestampTime) の展開例:

TimestampTime >= toDateTime(fromUnixTimestamp64Milli({startDateMilliseconds:Int64}))
AND TimestampTime <= toDateTime(fromUnixTimestamp64Milli({endDateMilliseconds:Int64}))

時間インターバルマクロ

これらのマクロは、タイムスタンプのカラムをダッシュボードの粒度に合わせたインターバルにまとめます。通常は、時系列チャートの SELECT 句および GROUP BY 句で使用します。利用できるのは、折れ線グラフと Stacked-bar の可視化のみです。

Macro	Description
`$__timeInterval(column)`	`DateTime` カラムを `intervalSeconds` 単位のインターバルにまとめます
`$__timeInterval_ms(column)`	`DateTime64` カラムを `intervalMilliseconds` 単位のインターバルにまとめます

$__timeInterval(TimestampTime) の展開例:

toStartOfInterval(toDateTime(TimestampTime), INTERVAL {intervalSeconds:Int64} second)

ダッシュボードフィルタ用マクロ

Macro	Description
`$__filters`	ダッシュボードレベルのフィルタ条件に置き換えられます (ログソースを選択している必要があります)

グラフでログソースが選択されており、ダッシュボードフィルタが有効な場合、$__filters は対応する SQL の WHERE 条件に展開されます。ログソースが選択されていない場合、またはフィルタが適用されていない場合は、(1=1) に展開されるため、WHERE 句に含めても常に安全です。

クエリ結果の表示方法

ClickStack は、カラムの型に基づいて、クエリ結果のカラムをグラフ要素に自動的に対応付けます。対応付けのルールは、グラフの種類によって異なります。

折れ線グラフと積み上げ棒グラフ

役割	カラム型	説明
タイムスタンプ	最初の `Date` または `DateTime` カラム	x軸として使用されます。
シリーズ値	すべての数値カラム	各数値カラムは個別のシリーズとしてプロットされます。通常、これらは集計値です。
グループ名	String、Map、または Array カラム	任意です。グループ値が異なる行は、それぞれ別のシリーズとしてプロットされます。

円グラフ

役割	カラムの型	説明
スライスの値	最初の数値カラム	各スライスの大きさを決定します。
スライスのラベル	String、Map、または Array カラム	任意です。各一意の値がスライスのラベルになります。

Number チャート

ロール	カラムの種類	説明
Number	最初の数値カラム	最初の数値カラムの先頭行の値が表示されます。

テーブルチャート

すべての結果カラムが、そのままテーブルのカラムとして表示されます。

例

必要な system table へのアクセス権以下の例を play-clickstack.clickhouse.com 上で実行する場合は、otel_v2.otel_logs または otel_v2.otel_traces を指定する必要があります。

折れ線グラフ — サービス別の時間ごとのログ件数

このクエリは、ダッシュボードの粒度に合わせた時間間隔で区切り、サービスごとのログイベント数を集計します。

SELECT
  toStartOfInterval(TimestampTime, INTERVAL {intervalSeconds:Int64} second) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE TimestampTime >= fromUnixTimestamp64Milli({startDateMilliseconds:Int64})
  AND TimestampTime < fromUnixTimestamp64Milli({endDateMilliseconds:Int64})
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

ts (DateTime) は、x軸のタイムスタンプとして使用されます。
count (数値) は、系列の値としてプロットされます。
ServiceName (文字列) は、サービスごとに別々の線として表示されます。

折れ線グラフ — マクロを使う場合

簡潔にするため、マクロを使って同じクエリを記述すると次のようになります。

SELECT
  $__timeInterval(TimestampTime) AS ts,
  ServiceName,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filters
GROUP BY ServiceName, ts
ORDER BY ts ASC

積み上げ棒グラフ — 重大度別エラー数

SELECT
  $__timeInterval(TimestampTime) AS ts,
  lower(SeverityText),
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND lower(SeverityText) IN ('error', 'warn')
  AND $__filters
GROUP BY SeverityText, ts
ORDER BY ts ASC

テーブルチャート — 応答が最も遅いエンドポイント上位10件

SELECT
  SpanName AS endpoint,
  avg(Duration) / 1000 AS avg_duration_ms,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY SpanName
ORDER BY avg_duration_ms DESC
LIMIT 10

円グラフ — サービス別リクエスト分布

SELECT
  ServiceName,
  count() AS request_count
FROM otel_traces
WHERE $__timeFilter(Timestamp)
  AND $__filters
GROUP BY ServiceName

request_count (数値) は各スライスの大きさを決定します。
ServiceName (文字列) は各スライスのラベルを表します。

Number チャート — エラーの総数

SELECT
  count() AS total_errors
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND SeverityText = 'error'
  AND $__filters

最初の行の数値 total_errors が表示されます。

注記

SQL ベースの可視化は readonly モードを有効にして実行されるため、SELECT クエリのみ実行できます。
SQL ベースの可視化では、SQL クエリは必ず 1 つだけ指定する必要があります。複数クエリには対応していません。
SQL エディタでは、クエリパラメータとマクロの両方でオートコンプリート候補が表示されます。
SQL ベースの可視化にダッシュボードフィルタを適用するには、ログソースを選択する必要があります。正しくフィルタリングするには、ログソースをクエリ対象のテーブルに一致させる必要があります。

機能

ガイド