SQLベースの可視化

ClickStackでSQLクエリを使用して可視化を作成する

ClickStack は、生の SQL クエリに基づく可視化をサポートしています。これにより、ダッシュボード レベルの時間範囲、フィルター、チャートの描画と連携しながら、クエリ ロジックを完全に制御できます。

SQL ベースの可視化は、組み込みの Chart Explorer では対応しきれないことを行いたい場合に有用です。たとえば、テーブルを結合したり、chart builder ではサポートされていない複雑な集計を作成したりする場合です。

​

SQL ベースの可視化の作成

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

その後、次の手順で進めます。

1. クエリの実行先となる ClickHouse 接続 を選択します。
2. 必要に応じて ログソース を選択します。これにより、$__filters マクロを介してダッシュボードレベルのフィルタをグラフに適用できるようになります。
3. エディタで SQL クエリを記述し、クエリパラメータとマクロを使ってダッシュボードの時間範囲やフィルタと連携させます。
4. 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 ベースの可視化にダッシュボードフィルタを適用するには、ログソースを選択する必要があります。正しくフィルタリングするには、ログソースをクエリ対象のテーブルに一致させる必要があります。