# 대시보드 (.dash)

> DuckDB SQL을 담은 .dash 파일로 DuckLocal 대시보드를 만드세요. 차트, 교차 필터, AI 에이전트가 답할 수 있는 주석, ducklocal check로 검증하는 방법을 다룹니다.

Source: https://ducklocal.app/docs/ko/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
}
```

열면 위쪽에 숫자 세 개가 나란히 놓이고, 막대 차트와 선 차트가 나란히, 그 아래에 표가 표시됩니다. 각 쿼리는 이를 사용하는 차트가 몇 개든 한 번만 실행됩니다. `totals`는 카드 세 개를 모두 채우고, `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" { ... }
```

이름은 같은 종류 안에서 고유해야 합니다. 두 쿼리가 같은 이름을 가질 수 없고 두 차트도 마찬가지지만, 쿼리와 차트는 같은 이름을 써도 됩니다.

::: info New in 0.4.1
`view` 블록은 여러 쿼리가 공유하는 가공을 담고, `filter`는 여러 값을 모을 수 있으며(`multiple = true`), `timeline` 차트는 이벤트를 실제 시간 간격에 따라 배치하고, `dashboard` 블록 하나가 모든 `TIMESTAMPTZ`를 표시할 시간대를 정합니다.
:::

### source

| 속성 | 필수 | 값 |
| --- | --- | --- |
| `path` | 예 | `.csv`, `.tsv`, `.txt`, `.parquet`, `.json`, `.jsonl`, `.ndjson` 파일 하나(gzip으로 압축된 파일도 포함, 예: `.csv.gz`), 또는 그것들의 글롭(`exports/orders-*.csv`)을 하나의 릴레이션으로 읽습니다 |

source는 데이터 파일에 쿼리가 읽을 이름을 부여합니다. `source "sales"`라고 쓰면 쿼리에서 `FROM sales`라고 씁니다. 경로는 DuckLocal을 실행한 위치가 아니라 **`.dash` 파일을 기준으로 한 상대 경로**이므로 대시보드와 데이터를 함께 옮길 수 있습니다. `~`와 절대 경로도 됩니다.

source는 연결에 전혀 손대지 않습니다. 그 이름을 참조하는 각 쿼리 앞에 `WITH sales AS (…)`로 들어가므로 사이드바에 아무것도 나타나지 않고, 탭보다 오래 남지 않으며, source는 이 대시보드의 쿼리에 대해서만 같은 이름의 테이블을 가립니다. 이름은 단순 식별자(영문자, 숫자, `_`)여야 합니다. 워크북은 source가 될 수 없습니다. DuckLocal에서 열고 그것이 만드는 테이블을 쿼리하세요.

### view

view는 여러 쿼리가 공유하는 가공을 한 번만 적어 두는 블록입니다. 쿼리의 `sql`과 같은 규칙 아래 `sql` 속성 하나를 담고, 그 이름을 쓰는 모든 쿼리는 이를 테이블처럼 읽습니다.

```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처럼 그 이름을 쓰는 각 쿼리 앞에 놓이고 연결에는 아무것도 만들지 않습니다. 쿼리들이 같은 CTE를 반복해야 할 때, 예를 들어 중첩된 JSON을 평탄화할 때 사용하세요.

### query

| 속성 | 필수 | 값 |
| --- | --- | --- |
| `sql` | 예 | 읽기 전용 SQL 문 하나. [히어독](#heredocs) 또는 문자열 |

query 블록은 `sql`만 담습니다. [필터](#filters)를 위해 `$name`을 읽을 수 있습니다.

### plot

| 속성 | 대상 | 값 |
| --- | --- | --- |
| `type` | 모두, 필수 | `"line"`, `"bar"`, `"stacked_bar"`, `"area"`, `"scatter"`, `"pie"`, `"heatmap"`, `"histogram"`, `"map"`, `"timeline"`, `"table"`, `"card"`, `"text"` 중 하나 — 따옴표로 묶은 문자열 |
| `query` | `text`를 제외한 모두, 필수 | query 블록에 대한 참조: `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 (…)`이 됩니다. 표는 행 하나를 선택하므로 표에 `multiple`을 쓰면 검사 오류입니다 |

필터가 하는 일은 [필터](#filters)를 참고하세요.

### dashboard

선택 사항인 `dashboard` 블록 하나가 파일 전체의 설정을 담습니다.

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

`timezone`은 대시보드의 모든 `TIMESTAMPTZ`를 표시할 시간대이며, 그 시간대는 차트 위에 표시됩니다. 오프셋(`"+08:00"`), `"UTC"`, `"local"`을 받고 `Asia/Shanghai` 같은 IANA 이름은 받지 않습니다. 일반 `TIMESTAMP`는 시간대가 없어 적힌 그대로 표시되고, 필터가 고른 열은 저장된 값을 유지하므로 선택이 계속 일치합니다. 파일에는 `dashboard` 블록이 많아야 하나입니다.

## 차트 종류 {#plot-types}

| 종류 | 그리는 것 |
| --- | --- |
| `line` | 계열마다 선 하나, 채우지 않음 |
| `area` | 계열마다 채운 영역 |
| `bar` | 행마다 막대 하나, 계열마다 색 하나. `series`가 있으면 각 그룹 안에서 계열의 막대가 나란히 놓입니다. 계열이 하나면 각 막대에 값 레이블이 붙습니다 |
| `stacked_bar` | `x`마다 막대 하나에 `series`를 쌓습니다. 양수는 0에서 위로, 음수는 아래로 쌓이고 합계는 맨 위와 툴팁에 표시됩니다 |
| `heatmap` | `x`는 가로, `series`는 세로로 놓고 각 셀을 `y`에 따라 하나의 파란색 계열로 칠합니다(값이 클수록 진하고 다크 모드에서는 밝게). 쿼리가 반환하지 않은 조합은 비어 있습니다 |
| `histogram` | 숫자 `x`의 각 구간마다 행 수를 셉니다. 구간 폭은 반올림한 값입니다. 쿼리는 그룹화하지 말고 행 자체를 반환하게 하세요 |
| `scatter` | 점마다 점 하나, 연결하지 않음, 계열마다 색 하나 |
| `pie` | `x` 값마다 조각 하나, 크기는 `y`에 비례하고 큰 것부터. 8조각이 넘으면 작은 것들이 "other"로 합쳐집니다. 가운데에 합계가 있는 링으로 그려지며, 범례 항목을 클릭하면 조각을 분리하고 다시 클릭하면 되돌립니다 |
| `text` | 제목, 설명 텍스트 또는 둘 다. 쿼리는 실행되지 않습니다 |
| `map` | 행마다 `lat`과 `lng` 위치에 점 하나. [지도](#maps) 참고 |
| `timeline` | 행마다 이벤트 하나를 그 `x` 시간에, 다른 이벤트와의 실제 거리에 따라 배치하므로 간격이 드러납니다. `series`는 행위자마다 레인을 주고, `caption`은 무슨 일이 있었는지 말하며, `tooltip`은 마우스를 올렸을 때 표시할 열을 나열합니다. `y`를 받지 않고, 레인은 최대 12개, 이벤트는 최대 1,000개까지 그리며(그보다 많으면 고르게 줄이고 그 사실을 알려 줌), 시간을 읽을 수 없는 행은 그리지 않고 셉니다 |
| `table` | 쿼리 결과를 그리드로, 열 너비는 내용에 맞춥니다. 헤더를 클릭하면 정렬 |
| `card` | 큰 숫자 하나와 `title`을 레이블로. 천 단위로 묶고 긴 소수는 반올림하며(`11439704.020000005` → `11,439,704.02`), 잘라 내지 않고 카드에 맞게 축소합니다 |

차트에 마우스를 올리면 값이 표시되며, 축이 보여 주는 형식으로 포맷됩니다(`4400000`이 아니라 `4.4M`).

막대 차트는 **모든** 범주에 레이블을 붙입니다. 레이블이 막대 아래에 들어가지 않으면 차트가 옆으로 눕고 레이블은 왼쪽 열에 놓입니다. 레이블을 줄이는 것은 시간 축뿐이며, 들어가는 만큼(항상 처음과 마지막을 포함) 유지합니다. 또한 `DATE` 열의 막대 차트는 쿼리가 아무것도 반환하지 않은 날을 빈 띠로 채우므로, 조용한 구간이 사라지지 않고 간격으로 읽힙니다. 선, 영역, 산점도 축도 같은 방식으로 레이블을 줄입니다.

x축은 모든 차트 종류에서 범주형입니다. 값은 서로의 거리가 아니라 쿼리가 반환한 순서대로 같은 간격으로 배치됩니다. 따라서 두 숫자 열의 `scatter`는 진정한 x–y 플롯이 아닙니다.

행은 쿼리가 반환한 순서대로 그려지므로, 차트에 데이터를 공급하는 쿼리는 `ORDER BY`로 끝내세요.

::: info New in 0.4.0
시간에 대한 대시보드의 `line`이나 `scatter`는 시간 위치에 따라 배치되므로 불규칙한 간격이 그대로 보이고, `ORDER BY`와 무관하게 시간 순서로 그려집니다. 시간이 NULL인 행은 안내와 함께 제외됩니다. 쿼리가 반환한 측정값이 NULL이면 선이 끊깁니다. `area`는 균등 간격을 유지하며 그 사실을 알려 줍니다. 계열은 이름별로 색을 유지하고, 모든 차트는 쿼리가 잘렸을 때 그 사실을 알려 줍니다.
:::

카드는 쿼리의 첫 행을 보여 줍니다. 쿼리가 둘 이상의 행을 반환하면 그 사실을 숫자 아래에 알리고, 하나도 반환하지 않으면 `—`를 보여 줍니다.

### 카드와 텍스트 패널 {#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"` | 금액, 소수 두 자리 |
| `"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`짜리 카드 네 개가 숫자 행을 만들고 그 아래에 `width = 6` 차트 두 개가 나란히 놓입니다. 열 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 Mercator 투영 위에 도 단위로 레이블을 붙인 위도·경도 그리드를 배경으로 표시합니다.

- **`color`**: 값이 최대 다섯 개까지 각각 색을 받습니다. 그보다 많으면 가장 흔한 네 개가 색을 받고 나머지는 "Other" 색을 공유합니다. 범례로 확인할 수 있습니다. 생략하면 결과에 값의 종류가 적은 텍스트 열이 있을 때 그 열로 점을 색칠합니다.
- **`size`**: 점의 *면적*이 값에 비례하므로 값이 두 배면 잉크도 두 배가 됩니다. 값의 자릿수가 크게 다르면 `size_scale = "log"`가 적합합니다. 모서리의 범례에서 크기를 확인할 수 있습니다.
- **`tooltip`**: 지정하지 않으면 점의 툴팁에 size 열과 나머지 숫자들, 그다음 좌표가 나옵니다.

점 아래에 지도는 **OpenStreetMap** 기본 지도를 그릴 수 있습니다. 타일을 불러오려면 네트워크가 필요하므로 켜기 전까지는 꺼져 있습니다 — **보기 → 온라인 기본 지도 (OpenStreetMap)**. 전송되는 것은 어떤 지도 타일을 원하는지뿐이며, 이는 대략 어느 지역을 보고 있는지를 드러낼 뿐 여러분 데이터의 행은 아닙니다. 타일은 일주일 동안 디스크에 캐시됩니다([설정과 앱 데이터](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이 그중 하나면 `OR "channel" IS NULL`이 붙습니다. 여러 필터는 쿼리가 이들을 조합하는 방식대로 조합됩니다.

- **막대 차트에서** 막대를 클릭해 고릅니다. 고른 막대는 색을 유지하고 나머지는 흐려집니다. 다시 클릭하면 선택이 해제됩니다. `multiple = true`이면 클릭할 때마다 값이 더해지고 다시 클릭하면 빠집니다.
- **표에서** 클릭하거나 화살표 키로 행을 선택합니다.
- 적용 중인 선택은 차트 위에 칩으로 표시됩니다. 각 칩의 ✕로 해당 필터를 지우고, **모두 지우기**로 모든 선택을 지웁니다. 다중 선택 필터는 고른 값마다 칩 하나를 표시합니다.
- **선택한 차트는 자기 필터로 좁혀지지 않습니다.** 채널이 선택된 동안에도 그 쿼리는 `$channel`을 `TRUE`로 읽습니다. 그렇지 않으면 클릭 한 번에 막대 차트가 방금 클릭한 막대로 줄어들어 다음에 클릭할 것이 남지 않기 때문입니다. 이것이 Mosaic나 crossfilter에서 말하는 교차 필터링입니다.
- **바뀐 것만 다시 실행됩니다.** 선택은 그 SQL을 바꾸는 쿼리만 다시 실행하고, 필터를 읽지 않는 쿼리는 결과를 유지합니다.

필터는 한 번에 값 하나를, `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` 파일을 열어도 여러분의 데이터는 바뀌지 않습니다.
- **쿼리당 문 하나.**
- **다른 쿼리 안의 `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`에서도 적용됩니다.

DuckDB는 SQL에 직접 이름을 쓴 단일 파일에 대해서는 여전히 작업 디렉터리를 먼저 확인하므로, 같은 이름의 파일이 있으면 그것이 우선할 수 있습니다. [source](#source) 블록은 경로를 대시보드 폴더 기준으로 명시적으로 해석해 이런 모호함을 피합니다. 절대 경로와 등록된 뷰는 그대로 사용할 수 있습니다.

## 제한

| 제한 | 동작 |
| --- | --- |
| 차트당 계열 12개 | 추가 계열은 제외되고, 몇 개였는지 알려 줍니다 |
| 계열당 점 1,500개 | 점을 구간 평균으로 줄여 맞춥니다 |
| 막대 200개 | 추가 막대는 제외됩니다 |
| 원형 조각 8개 | 가장 작은 것들이 하나의 "other" 조각으로 합쳐집니다 |
| 히트맵 열 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`는 개수와 unresolved 및 empty 쿼리 이름을 한 줄의 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.…`의 이름을 고치세요 |
| `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)에 있습니다.
