SQLベースの可視化

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

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

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

ここからは、次の手順で進めます。

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

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

使用できるパラメータは、チャートの種類によって異なります。

折れ線グラフ チャートおよび 積み上げ棒グラフ チャート:

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

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

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

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

$__timeFilter(TimestampTime) の展開例:

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

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

$__timeInterval(TimestampTime) の展開例:

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

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

$__filters によって適用されるのは、ブロードキャストフィルタ条件が有効なフィルタのみです。変数として公開されているフィルタは、以下で説明するように明示的に参照します。

ダッシュボードフィルタが変数として利用可能な場合、選択された値をクエリ内の任意の場所で参照できます。これらのマクロは、少なくとも1つの変数を宣言しているダッシュボードに属するタイルでのみ使用できます。

変数の値は、オプションのフォーマットを指定して $name または ${name} として直接補間することもできます。指定できる形式は ${name:sqlstring} (デフォルト) 、${name:csv}、${name:regex} です。デフォルト形式では、何も選択されていない場合、直接参照は NULL としてレンダリングされます。そのため、述語が必要な箇所では、可能な限り上記のマクロを使用してください。

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

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

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

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

ServiceName の service 変数と SeverityText の severity 変数を含む dashboard では、このクエリにより、グラフは現在選択されている service に絞り込まれ、選択した重要度は除外されます。どちらのマクロも対応する変数が未選択の場合は 1=1 に展開されるため、閲覧者が値を選択するまでグラフはフィルタリングされずに表示されます。

SELECT
  $__timeInterval(TimestampTime) AS ts,
  count() AS count
FROM otel_logs
WHERE $__timeFilter(TimestampTime)
  AND $__filter(ServiceName, $service)
  AND $__conditionalAll(SeverityText NOT IN ($severity), $severity)
GROUP BY 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

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 (文字列) は各スライスのラベルを表します。

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 ベースの可視化にダッシュボードフィルタを適用するには、ログソースを選択する必要があります。正しくフィルタリングするには、ログソースをクエリ対象のテーブルに一致させる必要があります。
• ダッシュボード変数にはログソースは不要です。値はタイル自体のログソースではなく、ダッシュボードのフィルタドロップダウンから取得されます。
• ダッシュボード変数を参照する SQL タイルのアラートは、ダッシュボードで選択された値ではなく、すべての変数が空の状態で評価されます。