# ダッシュボード (.dash)

> DuckDB SQL の .dash ファイルとして DuckLocal のダッシュボードを作成：グラフ、クロスフィルター、AI エージェントが回答できるコメント、ducklocal check による検証。

Source: https://ducklocal.app/docs/ja/dashboards

`.dash` ファイルはダッシュボードをデータとして記述します。**source** ブロックがデータファイルに名前を付け、**query** ブロックが SQL を持ち、**plot** ブロックが結果を描画し、**filter** ブロックによって、あるグラフをクリックすると他のグラフを絞り込めるようになります。書くコードはありません。人も AI エージェントも、ファイルを作成し、diff でレビューし、誰かが開く前に検証できます。

`.dash` ファイルは保存されたクエリから標準的なグラフ、表、数値、地図を描画します。そのプレーンテキスト形式は AI エージェントとの協働にも役立ちます。エージェントがファイルを書いたり編集したりし、`ducklocal check` が実行できることを検証し、あなたは [グラフにコメント](#review-with-comments) して変更を依頼します。

## 完全な例 {#a-complete-example}

このダッシュボードは [チュートリアルのサンプルファイル](tutorial.md#sample-file) をクエリします。[sales.dash](https://ducklocal.app/docs/samples/sales.dash) を `sales.csv` と同じディレクトリにダウンロードしてから、開いてください。

```hcl
source "sales" {
  path = "sales.csv"
}

query "totals" {
  sql = <<SQL
    SELECT round(sum(revenue), 2) AS revenue, sum(orders) AS orders,
           count(DISTINCT region) AS regions
    FROM sales
    WHERE $channel
  SQL
}

query "by_channel" {
  sql = <<SQL
    SELECT channel, round(sum(revenue), 2) AS revenue
    FROM sales
    GROUP BY channel
    ORDER BY revenue DESC
  SQL
}

query "daily" {
  sql = <<SQL
    SELECT date, region, round(sum(revenue), 2) AS revenue
    FROM sales
    WHERE $channel
    GROUP BY date, region
    ORDER BY date
  SQL
}

plot "revenue" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  width = 4
}

plot "orders" {
  type  = "card"
  query = query.totals
  value = orders
  title = "Orders"
  width = 4
}

plot "regions" {
  type  = "card"
  query = query.totals
  value = regions
  title = "Regions"
  width = 4
}

plot "revenue_by_channel" {
  type  = "bar"
  query = query.by_channel
  x     = channel
  y     = revenue
  title = "Revenue by channel"
  width = 5
}

plot "daily_revenue" {
  type   = "line"
  query  = query.daily
  x      = date
  y      = revenue
  series = region
  title  = "Daily revenue, per region"
  width  = 7
}

plot "daily_table" {
  type  = "table"
  query = query.daily
  title = "The numbers behind it"
}

filter "channel" {
  plot = plot.revenue_by_channel
}
```

開くと、上部に 3 つの数値が並び、棒グラフと折れ線グラフが横に並び、その下に表が表示されます。各クエリは、それを参照するグラフがいくつあっても 1 回だけ実行されます。`totals` は 3 つのカードすべてに、`daily` は折れ線グラフと表の両方にデータを供給します。**Revenue by channel** の棒をクリックすると、カード、折れ線グラフ、表がそのチャネルに絞り込まれます。棒グラフ自体は全体のまま残るので、別の棒をクリックできます。

## ダッシュボードを開く

次のいずれかの方法で、`.dash` ファイルがクエリの隣にダッシュボードタブとして開きます。

- タブバーの末尾にある **+** を押し、**ダッシュボードを開く** を選択する。
- ファイルをウィンドウにドラッグする。
- コマンドラインで指定する：`ducklocal sales.dash`。
- スクリプトやエージェントから、すでに起動しているウィンドウに対して実行する：`ducklocal open sales.dash`（[CLI ガイド](cli.md#show-work-in-the-running-window) を参照）。

グラフは 12 列のグリッドに配置されます。各グラフは [`width`](#layout) 分の幅を使い、グラフは左から右へ行を埋め、収まらなくなったグラフは次の行の先頭に移ります。行の間の区切り線をドラッグすると高さを変更できます。タブより高くなったダッシュボードはスクロールします。描画できないグラフ（クエリが失敗した、列が存在しないなど）は、その理由を自身のパネルに表示し、ダッシュボードの残りは描画され続けます。開いていたダッシュボードは次回起動時に復元され、最近開いたものはサイドバーの **ダッシュボード** に一覧表示されます。

グラフにカーソルを合わせると、右上隅にコントロールが表示されます。

- **SQL** を押すと、そのグラフがクエリの最後に実行した SQL に切り替わります。ソースと現在のフィルター選択が反映されているので、そのまま実行できます。**コピー** と **クエリタブで開く** もここから使えます。**グラフ** を押すと元に戻ります。
- 吹き出しアイコンを押すと、グラフの [コメント](#review-with-comments) が開きます。
- **このグラフを拡大** はグラフをダッシュボードタブ全体に広げます。**ダッシュボードに戻る (Esc)** を押すか **Esc** キーを押すとグリッドに戻ります。

SQL 表示では構文がハイライトされます。ダッシュボードの表のセルを右クリックすると、そのセル、タブ区切りの行、または表示順のその列をコピーできます。

`table` グラフの列ヘッダーをクリックすると並べ替えできます。降順、昇順、そしてクエリの順序に戻ります。数値は数値として並べ替えられ、`NULL` は最後になります。[フィルター](#filters) で選択した行は、並べ替えても選択されたままです。

ツールバーの **スペックを表示** は、タブをファイルのエディタに切り替えます。構文ハイライト（ヒアドキュメント内の SQL は SQL エディタと同じように色付けされます）、補完、インライン診断が使えます。**保存** または **⌘S** で書き戻して再描画します。保存したファイルが検証に失敗した場合、タブは最後に正常に動作したダッシュボードを保ち、その上にエラーを表示します。他のプログラムがファイルを変更した場合も同じです。**ダッシュボードに戻る** でグラフの表示に戻ります。**再読み込み** はファイルを読み直し、すべてのクエリを再実行します。

## コメントでレビューする {#review-with-comments}

コメントを使うと、文書をレビューするのと同じようにダッシュボードをレビューし、変更を AI エージェントに任せられます。このワークフローの背景にある製品思想は [Claude のダッシュボードから学んだ DuckLocal の姿](https://ducklocal.app/blog/claude-dashboards-ducklocal/) で解説しています。

**ウィンドウで**：グラフにカーソルを合わせ、吹き出しアイコンをクリックします。ダッシュボードの上にカードが開き、グラフのタイトルが引用され、すでにあるスレッドと書き込み用のボックスが表示されます。変更したいことを書き（*「大きいチャネルが先に来るように並べ替えて」*）、**コメント** を押します（または **⌘/Ctrl+Enter**）。各スレッドには **返信** と **解決** があります。解決したスレッドは、誰かが返信するまで薄く表示されたまま残ります。未解決のスレッドがあるグラフには、その件数付きの吹き出しが表示され続けるので、何が待っているかがひと目でわかります。

**エージェント** は [`ducklocal comments`](cli.md#review-comments-on-a-dashboard) でスレッドを読み、返信します。ウィンドウは不要です。

```bash
ducklocal comments sales.dash
```

```json
{
  "file": "sales.dash",
  "comments_file": "sales.dash.comments.json",
  "open": 1,
  "threads": [
    {
      "id": "c1",
      "plot": "revenue_by_channel",
      "plot_title": "Revenue by channel",
      "plot_query": "by_channel",
      "plot_lines": [68, 75],
      "plot_missing": false,
      "resolved": false,
      "comments": [
        { "author": "user", "text": "Rank these, biggest channel first", "at": "2026-10-10T14:03:00+08:00" }
      ]
    }
  ]
}
```

各スレッドは、対象のグラフ、そのグラフのクエリ、ファイル内の `plot` ブロックの行番号を示すので、エージェントは何を編集すべきかわかります。エージェントはスペックを変更し、`ducklocal check` を実行して、返信します。

```bash
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve
```

ウィンドウは両方のファイルを監視します。1 秒以内にグラフが編集後のスペックから再描画され、エージェントの返信がスレッドに **エージェント** の印付きで表示されます。

スレッドはダッシュボードの隣、`NAME.dash.comments.json` に保存されるので、`source` ファイルと同じようにダッシュボードと一緒に移動します。これらは作業メモであり、ダッシュボードの一部ではありません。バージョン管理から外すか、レビューが終わったらファイルを削除してください。

[公式のエージェントスキル](cli.md#install-the-official-skill) はこのループを教えるので、それを導入したエージェントには *「sales.dash のコメントに対応して」* と伝えるだけで済みます。

::: info New in 0.4.0
エージェントはファイルを編集する代わりに [変更を提案](agent-workflows.md#propose) できます。その場合タブに **レビュー** が表示され、diff とチェック結果を確認できます。適用できるのはあなただけです。
:::

### エージェントの作業を見る {#agent-presence}

開いているダッシュボードに対してエージェントが `check`、`comments`、`presence` を実行している間、その名前が隅に表示され、開発元のマーク（Claude、OpenAI、Gemini、Cursor、DeepSeek）または頭文字が添えられます。名前をクリックするとセッションログを確認できます。エージェントがファイルを編集すると、変更・追加されたグラフには印が付きます（**Claude が変更**、**Claude が追加**）。しばらく画面に表示すると印は消えます。削除されたグラフは、閉じられる通知として残ります。

エージェントは次の編集を `ducklocal presence sales.dash --doing editing --plot revenue_by_channel` で予告できます。そのグラフには枠が付き、まだ存在しないグラフ名の場合はダッシュボードの下にプレースホルダーが表示されます。セッションは 30 秒間操作がないか、明示的に `--doing idle` を指定すると終了します。作業を終えたエージェントは、回答したスレッドがあなたの返信を待っている間、アバターに件数を表示して隅に残ります。コメントにはどのエージェントが書いたかが記録され、そのマークが表示されます。オプションの詳細は [CLI リファレンス](cli.md#agent-presence) にあります。これらの表示はローカルの動作を示すもので、エージェントに作業を送信するものではありません。

## ブロック {#blocks}

ファイルはブロックの並びで、各ブロックは種類、引用符で囲んだ名前、本体からなります。

```hcl
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }
```

名前は同じ種類の中で一意でなければなりません。2 つのクエリが同じ名前を持つことはできず、2 つのグラフも同様です。ただしクエリとグラフは同じ名前でもかまいません。

::: info New in 0.4.1
`view` ブロックは複数のクエリが共有する整形処理を保持し、`filter` は複数の値（`multiple = true`）を集められ、`timeline` グラフはイベントを実際の時間間隔に沿って配置し、1 つの `dashboard` ブロックがすべての `TIMESTAMPTZ` を表示するタイムゾーンを設定します。
:::

### source

| 属性 | 必須 | 値 |
| --- | --- | --- |
| `path` | はい | `.csv`、`.tsv`、`.txt`、`.parquet`、`.json`、`.jsonl`、`.ndjson` のいずれかのファイル（`.csv.gz` などの gzip 圧縮も可）、またはそれらのグロブ（`exports/orders-*.csv`）を 1 つのリレーションとして読み込みます |

source はデータファイルに、クエリが参照する名前を与えます。`source "sales"` と書けば、クエリでは `FROM sales` と書けます。パスは DuckLocal を起動した場所ではなく、**`.dash` ファイルを基準にした相対パス** です。そのためダッシュボードとデータをまとめて移動できます。`~` や絶対パスも使えます。

source は接続には一切触れません。その名前を参照する各クエリの前に `WITH sales AS (…)` として展開されるので、サイドバーには何も現れず、タブを閉じれば残りません。また source は、このダッシュボードのクエリに対してのみ、同じ名前のテーブルを隠します。名前は単純な識別子（英字、数字、`_`）でなければなりません。ワークブックを source にすることはできません。DuckLocal で開き、そこから生成されるテーブルをクエリしてください。

### view

view は複数のクエリが共有する整形処理を 1 回だけ書いて保持します。`sql` 属性を 1 つだけ持ち、クエリと同じルールに従います。view の名前を指定したクエリは、それをテーブルとして読みます。

```hcl
view "events" {
  sql = <<SQL
    SELECT r.eventName AS event_name, r.eventTime AS event_time
    FROM (SELECT unnest(Records) AS r FROM trail)
  SQL
}

query "totals" {
  sql = "SELECT count(*) AS events, count(DISTINCT event_name) AS kinds FROM events"
}
```

view は自分より上で定義された source と view を読み、名前は source と共有し、`$filter` は取りません。フィルターは view を読むクエリ側で読んでください。source と同様に、その名前を指定した各クエリの前に展開され、接続には何も作成しません。入れ子になった JSON を平坦化する CTE など、同じ CTE をクエリごとに繰り返すことになる場合に使ってください。

### query

| 属性 | 必須 | 値 |
| --- | --- | --- |
| `sql` | はい | 読み取り専用の SQL 文を 1 つ。[ヒアドキュメント](#heredocs) または文字列で指定 |

query ブロックは `sql` だけを持ちます。[フィルター](#filters) のために `$name` を参照できます。

### plot

| 属性 | 対象 | 値 |
| --- | --- | --- |
| `type` | すべて、必須 | `"line"`、`"bar"`、`"stacked_bar"`、`"area"`、`"scatter"`、`"pie"`、`"heatmap"`、`"histogram"`、`"map"`、`"timeline"`、`"table"`、`"card"`、`"text"` のいずれか（引用符で囲んだ文字列） |
| `query` | `text` 以外すべて、必須 | クエリブロックへの参照：`query.by_channel` |
| `x` | グラフ、必須 | 横軸の列。`pie` では各スライス、`histogram` ではビン分けする数値、`timeline` では時間。`table` はすべての列を表示するため不要 |
| `y` | グラフ、必須 | 描画する列。数値である必要があります。`pie` ではスライスの大きさ。`histogram` と `timeline` では不要 |
| `series` | `line`、`bar`、`stacked_bar`、`area`、`scatter`、`heatmap`、`timeline` | 値ごとに行を系列に分ける列。`heatmap` では行、`timeline` ではスイムレーン |
| `title` | すべて | グラフの見出し（引用符で囲んだ文字列）。カードではラベル |
| `width` | すべて | 12 列グリッドのうち何列分を占めるか（`1`〜`12`）。既定は 12、カードは 3 |
| `value` | `card` | 表示する列（先頭行から）。既定は最初の列 |
| `note` | `card` | 値の下に表示するテキスト。引用符で囲んだ文字列、または先頭行から読む列名 |
| `tone` | `card` | `"accent"`、`"good"`、`"warning"`、`"critical"`。上部の罫線と値の色を決める |
| `format` | グラフと `card` | 数値の形式。[数値の書式と変化](#number-formats-and-change) を参照。`map` と `table` では使わない |
| `delta` | `card` | 変化量を持つ数値の列。値の下に表示される |
| `delta_format` | `card` | 変化量の書式。既定はカードの書式 |
| `down_is_good` | `card` | `true` にすると下降を緑、上昇を赤で表示。コスト、レイテンシ、解約率などに使う |
| `description` | すべて、**0.4.0+** | グラフが何を示し、どう読むか。タイトル横の ⓘ にカーソルを合わせると表示される |
| `text` | `text` | 本文を文字列またはヒアドキュメントで指定。`query` を付けず、`title` と `text` のいずれか、または両方を指定 |
| `caption` | `timeline` | 各イベントが何だったかを示す列。収まる場合は点の下に、収まらない場合はカーソルを合わせたときに表示される |
| `lat`、`lng` | `map` | 緯度と経度の列（度単位）。数値列の名前が座標を示す場合（`lat`、`latitude`、`geo_lat`、`lng`、`lon`、`longitude`）はどちらも省略できる |
| `color` | `map` | ポイントの色分けに使う列。省略した場合、値の種類が少ないテキスト列があればそれが選ばれる |
| `size` | `map` | ポイントの大きさに使う数値列 |
| `size_scale` | `map` | `size` のスケール方法として `"sqrt"`（既定）または `"log"` |
| `tooltip` | `map` | ポイントのツールチップに表示する列のリスト：`[name, passengers]` |

列の属性はクエリ結果の列名を指定するもので、大文字と小文字は区別されません。単純な名前は引用符なしで書き（`x = date`）、単純な識別子でない場合は引用符で囲みます（`y = "revenue (EUR)"`）。グラフの種類が使わない属性（折れ線での `lat`、地図での `x`、円グラフでの `series` など）は、黙って無視されるのではなくエラーになります。

### filter

| 属性 | 必須 | 値 |
| --- | --- | --- |
| `plot` | はい | クリックで値を選ぶ対象のグラフ：`plot.revenue_by_channel`。`bar`、`stacked_bar`、`table` のいずれか |
| `column` | `table` の場合 | 値を選ぶ列。`bar` または `stacked_bar` では省略時に `x` が使われる |
| `multiple` | `bar`、`stacked_bar` | `true` にするとクリックするたびに値を追加し、もう一度クリックすると外れる。`$name` は `IN (…)` になる。表は 1 行を選ぶため、表での `multiple` はチェックエラーになる |

フィルターの動作は [フィルター](#filters) を参照してください。

### dashboard

任意で 1 つの `dashboard` ブロックを置き、ファイル全体の設定を持たせられます。

```hcl
dashboard "Ops" {
  timezone = "+08:00"     # or "UTC", or "local"
}
```

`timezone` はダッシュボード内のすべての `TIMESTAMPTZ` を表示するタイムゾーンで、そのゾーン名はグラフの上に表示されます。オフセット（`"+08:00"`）、`"UTC"`、`"local"` を指定できます。`Asia/Shanghai` のような IANA 名は指定できません。`TIMESTAMP` はタイムゾーンを持たないため書かれたまま表示され、フィルターで選んだ列は選択が引き続き一致するように保存された値のまま扱われます。1 つのファイルに置ける `dashboard` ブロックは最大 1 つです。

## グラフの種類 {#plot-types}

| 種類 | 描画内容 |
| --- | --- |
| `line` | 系列ごとに 1 本の線（塗りつぶしなし） |
| `area` | 系列ごとに塗りつぶした領域 |
| `bar` | 行ごとに 1 本の棒、系列ごとに 1 色。`series` を指定すると、各グループ内で系列の棒が横に並ぶ。系列が 1 つの場合は各棒に値のラベルが付く |
| `stacked_bar` | `x` ごとに 1 本の棒を `series` で積み上げる。正の値は 0 から上、負の値は下に積まれ、合計は上部とツールチップに表示される |
| `heatmap` | `x` を横、`series` を縦に取り、各セルを `y` で 1 色の濃淡（値が大きいほど濃く、ダークモードでは明るく）に塗る。クエリが返さない組み合わせは空のまま |
| `histogram` | 数値 `x` の範囲ごとに行を数える。ビンの幅は切りのよい値。クエリはグループ化せず、行そのものを返すようにする |
| `scatter` | ポイントごとに 1 つの点（線で結ばない）、系列ごとに 1 色 |
| `pie` | `x` の値ごとに 1 つのスライス、大きさは `y` に比例し、大きい順。8 スライスを超えると小さいものが「その他」にまとめられる。ドーナツ型で描画され、中央に合計が表示される。凡例の項目をクリックするとスライスを分離でき、もう一度クリックすると元に戻る |
| `text` | タイトル、説明テキスト、またはその両方。クエリは実行されない |
| `map` | 行ごとに 1 つのポイントを `lat` と `lng` の位置に描く。[地図](#maps) を参照 |
| `timeline` | 行ごとに 1 つのイベントを `x` の時刻に描き、他のイベントとの実際の時間間隔に応じて配置するので、間隔の空きがそのまま見えます。`series` はアクターごとのスイムレーンを作り、`caption` は何が起きたかを示し、`tooltip` はカーソルを合わせたときに表示する列を指定します。`y` は取りません。最大 12 レーン、1,000 イベントまで描画し（それを超えると均等に間引いてその旨を表示）、時刻を読み取れない行は描画せず件数として数えます |
| `table` | クエリ結果をグリッド表示。列幅は内容に合わせて調整される。ヘッダーをクリックすると並べ替え |
| `card` | 大きな数値 1 つと、`title` をラベルにしたもの。3 桁区切りで表示され、長い小数は丸められ（`11439704.020000005` → `11,439,704.02`）、切り詰めずにカードに収まるよう縮小される |

グラフにカーソルを合わせると値が表示され、軸と同じ書式で整形されます（`4400000` ではなく `4.4M`）。

棒グラフは **すべての** カテゴリにラベルを付けます。ラベルが棒の下に収まらない場合、グラフは横向きになり、ラベルは左側の列に並びます。ラベルを間引くのは時間軸だけです。収まる数だけ、必ず最初と最後を含めて表示します。また `DATE` 列の棒グラフでは、クエリが何も返さなかった日が空の帯として埋められるので、データがない期間は消えるのではなく隙間として読めます。折れ線、面、散布図の軸も同じようにラベルを間引きます。

x 軸はどのグラフでもカテゴリ軸です。値は互いの距離ではなく、クエリが返す順に等間隔で配置されます。そのため、2 つの数値列による `scatter` は真の x–y プロットではありません。

行はクエリが返す順に描画されるので、グラフに渡すクエリの最後には `ORDER BY` を付けてください。

::: info New in 0.4.0
ダッシュボードの `line` や `scatter` で時間を扱う場合、点は時間に沿って配置されるため、間隔のばらつきがそのまま見た目に表れ、`ORDER BY` に関係なく時間順に描画されます。時間が NULL の行は除外され、その旨が表示されます。クエリが返した読み取り値が NULL の場合、線は途切れます。`area` は等間隔のままで、そのことが明示されます。系列は名前ごとに色を保ち、クエリが途中で切り詰められた場合はどのグラフでもその旨が表示されます。
:::

カードはクエリの先頭行を表示します。クエリが複数行を返す場合、その旨が数値の下に表示されます。1 行も返さない場合は `—` を表示します。

### カードとテキストパネル {#cards-and-text-panels}

カードは `note` で数値を説明し、`tone` で状態に応じた色を付けられます。同じ行にあるカードは数値のフォントサイズを共有します。テキストパネルは SQL を実行せずに見出しや補足を追加します。

```hcl
plot "revenue_summary" {
  type  = "card"
  query = query.totals
  value = revenue
  title = "Revenue"
  note  = "Current channel selection"
  tone  = "accent"
  width = 4
}

plot "reading_guide" {
  type  = "text"
  title = "How to read this dashboard"
  text  = "Click a channel to filter the daily chart and revenue cards."
  width = 8
}
```

テキストパネルが受け付けるのは `type`、`title`、`text`、`width` だけです。長い説明には `text = <<TEXT` と閉じる `TEXT` 行を使います。グラフ、円グラフ、地図では 8 色の異なる色相を使い、現在のテーマに合わせて濃淡を調整し、複数の系列がある場合は凡例を表示します。

### 数値の書式と変化 {#number-formats-and-change}

`format` はカードの値、値軸、棒のラベル、ツールチップの表示を整形します。

| 値 | 表示 |
| --- | --- |
| `"num0"`、`"num1"`、`"num2"` | 指定した小数桁数の数値 |
| `"pct"`（`"pct1"` と同じ）、`"pct0"`、`"pct2"` | 割合。0.421 は 42.1% と表示されるので、×100 せずに小数を返す |
| `"usd"`、`"eur"`、`"gbp"`、`"cny"` | 通貨。小数 2 桁 |
| `"usd0"`、`"eur0"`、`"gbp0"`、`"cny0"`、`"jpy"` | 通貨。整数単位 |

カードは `delta` で変化量を、値の下に `▲ 12.3%` や `▼ $125` のように表示します。良い変化は緑、そうでない変化は赤になり、`note` がその後に続いて何との比較かを示します。変化量はカードのクエリで計算してください。

```hcl
plot "revenue_total" {
  type         = "card"
  query        = query.totals
  value        = revenue
  format       = "usd0"
  delta        = growth
  delta_format = "pct1"
  note         = "vs last week"
}
```

### レイアウト {#layout}

`width` はダッシュボードの 12 列のうち、グラフが何列分を占めるかです。グラフは書かれた順に左から行を埋め、次のグラフが収まらない場合は折り返します。たとえば `3` のカード 4 枚で数値の行ができ、その下に `width = 6` のグラフ 2 つが横に並びます。12 列に満たない行の残りは空になります。カードだけの行は低い高さで始まり、表だけの行は最も高い表の行数に合わせた高さ（グラフの高さが上限）で始まります。テキストパネルの行はテキストに合わせた高さになり、それ以外の行はグラフの高さで始まります。行のサイズ変更ハンドルはカーソルを合わせると表示されます。

### 地図 {#maps}

```hcl
plot "stations" {
  type       = "map"
  query      = query.stations
  lat        = geo_lat
  lng        = geo_lng
  color      = line
  size       = passengers
  size_scale = "log"
  tooltip    = [name, passengers]
}
```

地図は各行をポイントとして描画します。ポイントに合わせて調整した Web メルカトル図法を使い、度単位のラベルを付けた緯度経度グリッドの上に表示します。

- **`color`**：最大 5 つの値にそれぞれ色が割り当てられます。それを超える場合、最も多い 4 つに色が付き、残りは「その他」の色を共有します。凡例で対応を確認できます。省略した場合、結果に値の種類が少ないテキスト列があれば、その列で色分けされます。
- **`size`**：ポイントの *面積* が値に比例するので、値が 2 倍なら塗りも 2 倍になります。桁が大きく異なる値には `size_scale = "log"` が適しています。隅の凡例でサイズを確認できます。
- **`tooltip`**：指定しない場合、ポイントのツールチップには `size` の列とその他の数値、続いて座標が表示されます。

ポイントの下に、**OpenStreetMap** のベースマップを描画できます。タイルの読み込みにはネットワークが必要なため、有効にするまで（**表示 → オンラインベースマップ (OpenStreetMap)**）はオフです。送信されるのは要求するタイルの情報だけで、おおよそどのあたりを見ているかがわかる程度であり、データの行が送られることはありません。タイルは 1 週間ディスクにキャッシュされます（[設定とアプリデータ](settings-and-data.md#where-things-are-stored) を参照）。オフラインまたは無効のときは、地図は緯度経度グリッドだけの上に描画されます。同じ切り替えは、クエリ結果の **グラフ** タブの地図にも適用されます。

## フィルター {#filters}

フィルターはグラフをクリック可能にし、そこで選んだ値で他のクエリを絞り込めるようにします。

```hcl
filter "channel" {
  plot = plot.revenue_by_channel     # a click on a bar picks its channel
}

filter "day" {
  plot   = plot.days                 # a table: a selected row picks …
  column = day                       # … the value of this column
}

filter "channel" {
  plot     = plot.revenue_by_channel
  multiple = true                    # clicks collect channels
}

query "daily" {
  sql = "SELECT date, sum(orders) AS orders FROM sales WHERE $channel AND $day GROUP BY 1"
}
```

クエリはフィルターを **`$name` という条件** として読み取ります。条件を書く位置に書いてください。何も選ばれていない間は `TRUE` になるので、ダッシュボードはフィルターがない場合とまったく同じに開きます。値が選ばれると `("channel" = 'Web')` になります。フィルターの `column` で指定した列と、選んだ値が比較されます。`NULL` と表示されるセルは、SQL の NULL またはリテラル文字列 `NULL` に一致します。棒グラフや積み上げ棒グラフで `multiple = true` を指定すると、クリックするたびにその値が追加され、もう一度クリックすると外れ、`$name` は `("channel" IN ('Web', 'App'))` になります。NULL がその 1 つに含まれる場合は `OR "channel" IS NULL` が付きます。複数のフィルターは、クエリ内での結合方法に従って組み合わされます。

- **棒グラフでは**、棒をクリックすると選択されます。選択した棒は色を保ち、他の棒は薄くなります。もう一度クリックすると選択を解除します。`multiple = true` の場合は、クリックするたびに値が追加され、もう一度クリックすると外れます。
- **表では**、クリックまたは矢印キーで行を選択します。
- 有効な選択はグラフの上にチップとして表示されます。各チップの ✕ でそのフィルターを解除でき、**すべてクリア** ですべての選択を解除します。複数選択のフィルターでは、選んだ値ごとに 1 つのチップが表示されます。
- **選択元のグラフは、自身のフィルターで絞り込まれることはありません。** チャネルが選択されていても、そのグラフのクエリは `$channel` を `TRUE` として読みます。そうでなければ 1 回のクリックで棒グラフがクリックした棒だけになり、次にクリックする対象がなくなってしまいます。これは Mosaic や crossfilter と同じクロスフィルタリングです。
- **変更があったものだけが再実行されます。** 選択によって SQL が変わるクエリだけが再実行され、フィルターを参照しないクエリは結果を保持します。

フィルターは同時に 1 つの値だけを保持します。`multiple = true` を使えば複数の値を保持できます。クリックでフィルターできるグラフには、タイトルの下にヒントが表示されます。フィルターで残るグループが変わっても、系列は色を保ちます。`$channel` を使うクエリは、その述語を使う位置でフィルターの列を公開している必要があります。`ducklocal check` は選択値バージョンのバインディングも行うようになったので、列の欠落は最初のクリック前に検出されます。

::: info New in 0.4.0
`NULL` と表示されるセルを選ぶと SQL の NULL だけが選択され、`'NULL'` というテキストはそれ自体だけを選択します。クリックでフィルターできるグラフには、タイトルの下のヒントが表示されなくなりました。
:::

選んだ値は引用符付きリテラルとして SQL に入り、比較時に DuckDB が列の型に変換するので、テキストだけでなく日付や数値も機能します。選択はタブを開いている間保持され、フィルターがファイルに残っていれば再読み込み後も引き継がれますが、起動をまたいで記憶されることはありません。

## 値

| 形式 | 例 | 使う場所 |
| --- | --- | --- |
| 文字列 | `"Revenue by channel"` | `type`、`title`、`path`、`size_scale`、`tone`、リテラルの `note`、`text`、引用符付きの列名、短い `sql` |
| ヒアドキュメント | `<<SQL` … `SQL` | `sql`、`text` |
| 参照 | `query.daily`、`plot.revenue_by_channel` | グラフの `query`、フィルターの `plot` |
| 裸の名前 | `channel` | 列の属性 |
| 数値 | `6` | `width` |
| リスト | `[name, "Unique IPs"]` | `tooltip` |

文字列はその行で終わり、`\n`、`\t`、`\"`、`\\` を解釈します。

`#` と `//` は行末までのコメントを開始します。属性に区切りは不要で、改行は単なる空白として扱われます。

言語はこれだけです。変数も関数も条件分岐もなく、フィルターの `$name` 以外の補間もありません。

### ヒアドキュメント {#heredocs}

ヒアドキュメントは複数行にわたるテキストを保持します。実際には SQL です。

```hcl
  sql = <<SQL
    SELECT 1
  SQL
```

- `<<` の後の区切り文字は任意の単語です（慣例では `SQL`）。その行では区切り文字の後に何も書けません。
- ヒアドキュメントは、前後の空白を除いて区切り文字だけの行が最初に現れた時点で終わります。
- 閉じる行のインデントはテキストの各行から取り除かれるので、SQL はブロックのインデントに合わせて書いてもそのインデントを引きずりません。

## SQL のルール {#sql-rules}

ダッシュボードは、開かれたとき、再読み込みされたとき、保存されたとき、そしてタブが復元されて DuckLocal が起動したときにクエリを実行します。そのためクエリは **読み取り** のみ可能です。

- **許可：** `SELECT`、`WITH …`、`FROM` で始まるクエリ、`VALUES`、`SHOW`、`DESCRIBE`、`SUMMARIZE`、`PIVOT`、`UNPIVOT`。
- **拒否：** データやファイルを変更しうるもの。`CREATE`、`INSERT`、`UPDATE`、`DELETE`、`DROP`、`COPY`、`ATTACH`、`INSTALL`、`LOAD` など。誰かから送られた `.dash` ファイルを開いても、データが変更されることはありません。
- **1 クエリにつき 1 文。**
- **他のクエリの内側にある `PIVOT` は値を明示します。** `PIVOT` で始まるクエリは、値を DuckDB に任せられます（`PIVOT orders ON channel USING sum(amount)`）。`SELECT` や `WITH` の内側に入れ子にする場合は、明示的なリストが必要です：`ON channel IN ('Web', 'Store')`。
- **`$name` はフィルターブロックを指している必要があります。** 読み取り専用チェックは、すべての `$name` を `TRUE` として SQL を判定します。文字列、引用符付き識別子、コメント、`$$ … $$` 文字列の中の `$` はそのまま扱われます。

クエリはウィンドウ自身の接続で実行されるため、SQL エディタが見ているものすべて（開いたファイル、アタッチしたデータベース、`TEMP` テーブルのような接続レベルの状態）を参照できます。

### SQL 内のパス

v0.2.2 以降、ダッシュボードの SQL にある相対ファイルパスは `.dash` ファイルのフォルダーからも検索されます。たとえば、別のディレクトリから開いた場合でも、`FROM 'sales.csv'` でダッシュボードの隣にある CSV を読めます。これはウィンドウでも `ducklocal check` でも同じです。

SQL 内で直接ファイル名を指定した場合、DuckDB は依然として作業ディレクトリを先に確認します。同じ名前のファイルがそこにあれば、そちらが優先されることがあります。[source](#source) ブロックはパスをダッシュボードのフォルダーを基準に明示的に解決するので、この曖昧さを避けられます。絶対パスや登録済みのビューも引き続き利用できます。

## 制限

| 制限 | 動作 |
| --- | --- |
| グラフあたり 12 系列 | それ以降の系列は除外され、いくつあったかを通知で表示 |
| 系列あたり 1,500 ポイント | 収まるようにポイントをバケット平均化 |
| 200 本の棒 | それ以降の棒は除外 |
| 8 つの円グラフスライス | 最小のものが 1 つの「その他」スライスにまとめられる |
| ヒートマップ 200 列、12 行 | それ以降の列と行は除外 |
| ヒストグラム 5〜40 ビン | 行数の平方根程度。各ビンの幅は 1、2、2.5、5 のいずれかに 10 の累乗を掛けた値 |
| 地図 20,000 ポイント | それ以降のポイントは除外され、その旨を通知で表示 |
| タイムラインあたり 12 レーン、1,000 イベント | それ以降のイベントは均等に間引かれ、その旨を通知で表示。時刻を読み取れない行は描画せず件数として数える |

## ダッシュボードを検証する {#validate-a-dashboard}

`ducklocal check` はウィンドウを開かずにファイルを検証します。ダッシュボードを誰かに渡す前に実行するステップです。

```bash
ducklocal check sales.dash
ducklocal check sales.dash --database warehouse.duckdb
ducklocal check sales.dash --summary
```

まず静的チェックを行います。構文、名前と参照、必須属性、すべての `$name` とフィルターブロックの対応、そして各クエリの SQL を DuckDB 自身のパーサーで検証します。次に **すべてのクエリが** 読み取り専用で、ソースを適用し、何も選択しない状態で実行され、各グラフの列がクエリが実際に返す列と照合されます。`y`、地図の座標と `size` が数値であること、各フィルターの `column` がそのグラフのクエリで返される列であることも確認されます。実行が重要なのは、失敗するキャストや何にも一致しないグロブは、行を読んで初めてわかるからです。

- **`--database` を指定しない場合**、クエリはメモリ内で実行されます。`source` ファイルだけを使うダッシュボードにはこれで十分です。どの source も定義していないテーブルを読むクエリは、失敗ではなく `unresolved` に一覧表示され、そのグラフの列はチェックされません。おそらくデータベース向けのクエリです。
- **`--database PATH` を指定した場合**、そのデータベースに対して読み取り専用で開いて実行されます。クエリがデータベースのテーブルを読む場合は必ず指定してください。

フィルターを使う各クエリは、選択値バージョンでもバインディングされます（そのバリアントは実行されません）。これにより、そのクエリで利用できない列を参照する述語を検出できます。誤りのあるブロックがあっても、正しいブロックのチェックは妨げられません。診断には同じ実行でのスペックエラーとクエリ失敗の両方が含まれます。

成功すると、ソース、クエリ（結果の列と各クエリが返した `rows` の数を含む）、フィルター、グラフの JSON サマリーに加えて、`empty`（実行されたが行を返さなかったクエリ）が出力されます。これはエラーではありませんが、多くの場合、正規表現、フィルター、結合が何にも一致しなかったことを意味するので、ダッシュボードを渡す前にそれぞれ確認してください。`--summary` は件数の 1 行 JSON と、未解決および空のクエリ名を出力します。誤りがあるとスペック診断としてステータス **2** で終了し、すべての問題を一度に `file:line: message` の形式で列挙します。SQL のみの失敗、データベースやファイルの失敗は **1** で終了します。詳細は [CLI ガイド](cli.md#check-a-dashboard-spec) にあります。

::: info New in 0.4.0
`ducklocal check FILE --restricted --allow-read PATH` は、自分が書いていないダッシュボードを制限付きでチェックします。[自分が書いていない SQL を制限する](agent-workflows.md#restricted) を参照してください。
:::

### よくあるメッセージ

| メッセージ | 修正方法 |
| --- | --- |
| `type is a string in quotes` | `type = "line"` と書き、`type = line` とは書かない |
| `Unknown plot type: "donut"; one of line, bar, area, scatter, pie, map, table, card, text` | 一覧にある種類のいずれかを使う |
| `plot block "p" requires y` | すべてのグラフの種類に `y` が必要（`table`、`map`、`card`、`text` は不要） |
| `plot "p" draws query "q", which the file does not define` | クエリブロックを追加するか、`query = query.…` の名前を修正する |
| `query names a query block: query = query.some_name` | `query` 属性は文字列ではなく参照を取る |
| `plot "p" draws y = "channel" (VARCHAR), which is not numeric` | `y` を数値列に向けるか、`type = "table"` を使う |
| `A map plot places points by lat and lng; it takes no x` | 地図に軸はない。`lat` と `lng` を指定するか、列名に任せる |
| `width is how many of the dashboard's 12 columns the plot spans` | 1 から 12 の整数を書く |
| `query "q" reads $chanel, but no filter block is named "chanel"` | 名前を修正するか、`filter` ブロックを追加する |
| `filter "f" picks on plot "p", a line; a value is picked on a bar or table plot` | フィルターを棒グラフか表に向ける |
| `a dashboard query must be a single read-only statement` | 書き込みは SQL エディタに移すか、入れ子の `PIVOT` の値を `IN` で明示する。[SQL のルール](#sql-rules) を参照 |
| `Unknown block: "card"; a card is a plot: plot "x" { type = "card" … }` | すべてのパネルは plot ブロック。カードやテキストパネルも同様 |
| `"minutes" is a SQL keyword, so as a column alias it needs AS` | `count(*) AS minutes` と書くか、エイリアスを引用符で囲む |
| `Unterminated heredoc: no line is exactly SQL` | 閉じる区切り文字を単独の行に書く |

## 自分のエディタで編集する

`ducklocal lsp` は `.dash` ファイル用の言語サーバーです。入力中の診断、ブロックの種類・属性・グラフの種類・`query.` と `plot.` の後の名前の補完、ホバーでのドキュメント表示、`query.name` や `plot.name` の参照からブロックへの定義ジャンプを提供します。Neovim と VS Code の設定は [CLI ガイド](cli.md#edit-a-dashboard-spec-with-lsp) にあります。
