ダッシュボードを作成する#

ダッシュボードは dashboards/<slug>/page.md ドキュメントと、必要に応じて同じフォルダーに置く .sql、.tsx ファイルで構成します。説明は Markdown で記述します。コンポーネントは、名前を付けたクエリ結果をチャート、テーブル、数値、ピボット、地図として表示します。

ページを作成する#

text

dashboards/revenue/
  page.md
  revenue-daily.sql

ページのタイトル、更新間隔、結果の上限、必要に応じてテーマをフロントマターに記述します。

text

---
title: Revenue
refresh: 4h
max_rows: 2000
theme: supernova
---

クエリを追加する#

ページから revenue-daily.sql を参照するには revenue-daily を使います。

sql

select
  cast(created_at as date) as day,
  sum(amount) / 100.0 as revenue
from titan.stripe.charges
where status = 'succeeded' and not _deleted
group by day
order by day

言語名を指定したインラインのコードフェンスもデータソースになります。例：``` `sql revenue-daily ```。長いクエリは同じフォルダーの別ファイルに分けるとレビューしやすくなります。

別のクエリを利用する#

同じダッシュボード内の別のクエリを queries.<name> として読み取れます。

sql

select sum(revenue) as revenue
from queries."revenue-daily"
where day >= $period.start

参照したクエリは指定した位置にインライン展開され、同じジョブ内で実行されます。クエリ間でデータを保存しないため、常に現在のデータを読み取ります。$period.start などの入力は、どちらのクエリでも使えます。存在しないクエリへの参照や、クエリ間の循環参照はページの上部に表示されます。

結果を表示する#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       title="Revenue by day" format={{"type":"money","currency":"USD"}} />

組み込みのデータコンポーネントは Chart、Table、BigNumber、Pivot、Map です。チャートの種類は line、bar、area、donut、pie、scatter です。関連するコンポーネントを同じ行に並べるには、<Row> の中に配置します。

目標値を示す#

text

<Chart data={revenue-daily} type="bar" x="day" y="revenue"
       goal={{"y":120000,"label":"Target"}} />

goal は数値軸に基準線を描き、必ず描画領域内に収まるように軸の範囲を広げます。配列を渡すと、下限、計画値、挑戦目標など、最大 4 本の線を表示できます。横棒グラフでは数値軸に沿うため、線は縦方向に描かれます。ドーナツチャートと円グラフには数値軸がないため、この指定は拒否されます。

特定の系列を強調する#

text

<Chart data={revenue-by-plan} type="line" x="day" y="revenue" series="plan" emphasis="enterprise" />

emphasis は指定した系列の色を維持し、ほかの系列を控えめな色にします。線、面、棒、点、凡例、ツールチップの色見本に一括して適用されます。名前の照合では大文字と小文字を区別しません。結果に一致する系列がなければ何も変更しないため、データからカテゴリがなくなってもチャートは壊れません。

特定の時点にラベルを付ける#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue"
       annotations={[{"x":"2026-03-01","label":"Price change"}]} />

注釈は、指定した x 座標に細い縦線を描き、描画領域の上部に小さなラベルを表示します。最大 8 個指定できます。x はクエリが実際に返した値である必要があります。フィルターで表示範囲が変わり、範囲外になった注釈は、端に移動させずに省略します。ラベルは長さを制限し、重なる場合は下の段へずらします。4 段を超えたラベルは表示せず、縦線だけを描きます。5 段目までテキストを置くと、グラフの領域が埋まってしまうためです。

同じクエリを数値とチャートで使う#

text

<BigNumber data={revenue-daily} value="revenue" label="Revenue" agg="sum" trend />

大きな数値の表示では、デフォルトで最初の行を読み取ります。agg を指定すると、列全体を sum、avg、last、first のいずれかで集計します。日別のクエリから、同じ行に基づくチャートと正確な合計を表示できます。trend は、その列を行の順に描いたスパークラインを数値の横に追加します。

整数の列は、浮動小数点の合計で誤差が生じる大きさでも正確に合計されるため、件数や ID の値を維持できます。ただし、デフォルトの compact 形式は表示時に丸めます。省略表示はそのための形式です。すべての桁が必要なら number または integer を指定してください。

前の期間と比較する#

text

<Chart data={revenue-daily} type="line" x="day" y="revenue" compare="prev-period" />
<BigNumber data={revenue-total} value="revenue" label="Revenue" compare="prev-year" />

compare は日付範囲を過去にずらして同じクエリをもう一度実行します。prev-period は現在の期間の長さだけ、prev-year は暦で 1 年ずらします。チャートは前の期間を現在の期間の下に薄く重ね、サブタイトルがなければ変化を説明文として追加します。大きな数値の表示では、値の横に変化を表示します。

ずらす対象を指定するため、クエリでは $period.start と $period.end で日付範囲を絞り込む必要があります。チャートが比較するのは 1 つの指標です。y のリスト、series、ドーナツチャートは使えません。大きな数値の表示では、compare が delta に優先します。

2 つの期間は行の順番ではなく、値に基づいて対応付けます。日付軸では、前の期間の各行をクエリに適用した量だけ先に移動します。ある日が欠けていれば、その位置に空白を残し、後続の値を左にずらしません。カテゴリ軸の上位 N 件チャートでは名前で対応付けます。前の期間だけ上位 N 件に入ったカテゴリは配置先がないため描画せず、今回初めて入ったカテゴリには過去の表示がありません。説明文の変化量は、チャートに収まらなかった行も含む前の期間全体で計算します。そのため、表示が一部に限られていても説明は正確なままです。

型付き入力を追加する#

text

<DateRange name="period" default="-30d" />
<Select name="currency" options={["usd","eur","gbp"]} default="usd" />

SQL から入力を参照するには $period.start、$period.end、$currency を使います。値は宣言に照らして検証され、プリペアドステートメントのパラメーターとしてバインドされます。URL の値を SQL 文字列に直接埋め込むことはありません。

TextInput、NumberInput、Select、DateRange を利用できます。Select に multiple を指定すると、上限付きのリストをバインドします。相対日付のプリセットには -30d、-2w、-6m、-1y、mtd、ytd、today、all があります。

ダッシュボードを拡張する#

ページ専用のコンポーネントは page.md と同じフォルダーに <Name>.tsx として追加し、共有コンポーネントは dashboards/components/ に配置します。カスタムコンポーネントには、上限付きのテーブルデータと、組み込みコンポーネントと同じテーマユーティリティが渡されます。