대시보드 (.dash)
.dash 파일은 대시보드를 데이터로 기술합니다. source 블록은 데이터 파일에 이름을 붙이고, query 블록은 SQL을 담고, plot 블록은 결과를 그리고, filter 블록은 한 차트를 클릭해 다른 차트를 좁힐 수 있게 합니다. 작성할 코드는 없습니다. 사람과 AI 에이전트 모두 파일을 만들고, diff에서 검토하고, 누구든 열기 전에 검증할 수 있습니다.
.dash 파일은 저장된 쿼리로 표준적인 차트, 표, 숫자, 지도를 그립니다. 일반 텍스트 형식이라 AI 에이전트와 함께 작업하기에도 유용합니다. 에이전트가 파일을 작성하거나 편집하고, ducklocal check가 실행되는지 검증하며, 여러분은 차트에 주석을 달아 변경을 요청합니다.
완전한 예제
이 대시보드는 튜토리얼의 샘플 파일을 쿼리합니다. sales.dash를 sales.csv와 같은 폴더에 내려받은 뒤 여세요.
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 가이드 참고).
차트는 12열 그리드에 배치됩니다. 각 차트는 width만큼의 열을 차지하고, 차트는 왼쪽에서 오른쪽으로 행을 채우며, 더 이상 들어가지 않는 차트는 다음 행에서 시작합니다. 행 사이의 구분선을 끌어 높이를 조절할 수 있습니다. 탭보다 높은 대시보드는 스크롤됩니다. 그릴 수 없는 차트는(쿼리가 실패했거나 열이 없음) 자체 패널에 이유를 표시하고, 나머지 대시보드는 계속 그려집니다. 열어 둔 대시보드는 다음 실행 시 복원되고, 최근에 연 것은 사이드바의 대시보드 아래에 나열됩니다.
차트에 마우스를 올리면 오른쪽 위 모서리에 컨트롤이 나타납니다.
- SQL을 누르면 차트가 그 쿼리가 마지막으로 실행한 SQL로 바뀝니다. 소스와 현재 필터 선택이 반영되어 있으므로 그대로 실행됩니다. 복사와 쿼리 탭에서 열기도 있습니다. 차트를 누르면 원래대로 돌아갑니다.
- 말풍선을 누르면 차트의 주석이 열립니다.
- 이 차트 확대는 차트를 대시보드 탭 전체로 펼칩니다. 대시보드로 돌아가기 (Esc) 를 누르거나 Esc를 누르면 그리드로 돌아갑니다.
SQL 보기에서는 구문이 강조됩니다. 대시보드 표의 셀을 마우스 오른쪽 버튼으로 클릭하면 그 셀, 탭으로 구분된 그 행, 또는 표시된 순서 그대로의 그 열을 복사할 수 있습니다.
table 차트의 열 헤더를 클릭하면 정렬됩니다. 내림차순, 오름차순, 그다음 쿼리의 순서로 돌아갑니다. 숫자는 숫자로 정렬되고 NULL은 마지막에 옵니다. 필터로 선택한 행은 정렬해도 선택된 상태로 남습니다.
도구 모음의 스펙 보기는 탭을 파일 편집기로 전환합니다. 구문 강조(히어독 안의 SQL은 SQL 편집기와 같은 색으로 표시됩니다), 자동 완성, 인라인 진단을 제공합니다. 저장 또는 ⌘S로 파일에 다시 쓰고 다시 그립니다. 저장한 파일이 검증에 실패하면 탭은 마지막으로 정상 동작한 대시보드를 유지하고 그 위에 오류를 표시합니다. 다른 프로그램이 파일을 바꾼 경우에도 마찬가지입니다. 대시보드로 돌아가기를 누르면 차트로 돌아갑니다. 다시 불러오기는 파일을 다시 읽고 모든 쿼리를 다시 실행합니다.
주석으로 검토하기
주석을 사용하면 문서를 검토하듯 대시보드를 검토하고 변경 사항을 AI 에이전트에게 맡길 수 있습니다. 이 워크플로 뒤에 있는 제품 사고는 Claude 대시보드가 DuckLocal에 가르쳐 준 것에서 다룹니다.
창에서: 차트에 마우스를 올리고 말풍선을 클릭합니다. 대시보드 위에 카드가 열리고 차트 제목을 인용하며, 이미 달린 스레드와 작성 상자가 표시됩니다. 무엇을 바꿀지 적고("가장 큰 채널이 먼저 오도록 정렬해 줘") 주석을 누릅니다(⌘/Ctrl+Enter). 각 스레드에는 답글과 해결이 있습니다. 해결된 스레드는 누군가 답글을 달 때까지 흐리게 남아 있습니다. 열린 스레드가 있는 차트에는 개수가 표시된 말풍선이 계속 보이므로 무엇이 대기 중인지 한눈에 알 수 있습니다.
에이전트는 ducklocal comments로 스레드를 읽고 답합니다. 창이 필요 없습니다.
ducklocal comments sales.dash{
"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를 실행한 뒤 답합니다.
ducklocal comments sales.dash --reply c1 --text "Sorted by revenue, descending" --resolve창은 두 파일을 모두 감시합니다. 1초 안에 편집된 스펙으로 차트가 다시 그려지고, 에이전트의 답글이 에이전트 표시와 함께 스레드에 나타납니다.
스레드는 대시보드 옆 NAME.dash.comments.json에 보관되므로 source 파일처럼 대시보드와 함께 이동합니다. 이는 작업 메모이며 대시보드의 일부가 아닙니다. 버전 관리에서 빼 두거나, 검토가 끝나면 파일을 삭제하세요.
공식 에이전트 스킬은 이 루프를 가르치므로, 이를 갖춘 에이전트에게는 *"sales.dash의 주석을 처리해 줘"*라고 말하기만 하면 됩니다.
New in 0.4.0
에이전트는 파일을 직접 편집하는 대신 변경을 제안할 수 있습니다. 그러면 탭에 diff와 검사 결과가 있는 검토가 표시되고, 적용은 여러분만 할 수 있습니다.
에이전트 작업 살펴보기
이 대시보드가 열려 있는 동안 에이전트가 check, comments, presence를 실행하면 그 이름이 모서리에 표시되고, 제작사 표시(Claude, OpenAI, Gemini, Cursor, DeepSeek) 또는 이니셜이 함께 나옵니다. 이름을 클릭하면 세션 로그를 볼 수 있습니다. 에이전트가 파일을 편집하면 변경되거나 추가된 차트가 잠시 화면에 둔 뒤 사라질 때까지 표시됩니다(Claude가 이 차트를 변경함, Claude가 이 차트를 추가함). 삭제된 차트는 닫을 수 있는 알림으로 남습니다.
에이전트는 ducklocal presence sales.dash --doing editing --plot revenue_by_channel로 다음 편집을 예고할 수 있습니다. 해당 차트에 테두리가 생기고, 아직 없는 차트 이름이면 대시보드 아래에 자리 표시자가 나타납니다. 세션은 30초 동안 활동이 없거나 --doing idle을 명시하면 끝납니다. 작업을 마친 에이전트가 답한 스레드가 여러분의 답글을 기다리는 동안에는 아바타에 개수를 표시하며 모서리에 남아 있습니다. 주석에는 어떤 에이전트가 썼는지 기록되고 그 표시가 나타납니다. 옵션은 CLI 레퍼런스에서 다룹니다. 이 표시는 로컬 활동을 보여 줄 뿐, 에이전트에 작업을 보내지는 않습니다.
블록
파일은 블록의 나열이며, 각 블록은 종류, 따옴표로 묶은 이름, 본문으로 이루어집니다.
source "name" { ... }
view "name" { ... }
query "name" { ... }
plot "name" { ... }
filter "name" { ... }
dashboard "name" { ... }이름은 같은 종류 안에서 고유해야 합니다. 두 쿼리가 같은 이름을 가질 수 없고 두 차트도 마찬가지지만, 쿼리와 차트는 같은 이름을 써도 됩니다.
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 속성 하나를 담고, 그 이름을 쓰는 모든 쿼리는 이를 테이블처럼 읽습니다.
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 문 하나. 히어독 또는 문자열 |
query 블록은 sql만 담습니다. 필터를 위해 $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 | 숫자의 형식: 숫자 형식과 변화 참고. 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을 쓰면 검사 오류입니다 |
필터가 하는 일은 필터를 참고하세요.
dashboard
선택 사항인 dashboard 블록 하나가 파일 전체의 설정을 담습니다.
dashboard "Ops" {
timezone = "+08:00" # or "UTC", or "local"
}timezone은 대시보드의 모든 TIMESTAMPTZ를 표시할 시간대이며, 그 시간대는 차트 위에 표시됩니다. 오프셋("+08:00"), "UTC", "local"을 받고 Asia/Shanghai 같은 IANA 이름은 받지 않습니다. 일반 TIMESTAMP는 시간대가 없어 적힌 그대로 표시되고, 필터가 고른 열은 저장된 값을 유지하므로 선택이 계속 일치합니다. 파일에는 dashboard 블록이 많아야 하나입니다.
차트 종류
| 종류 | 그리는 것 |
|---|---|
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 위치에 점 하나. 지도 참고 |
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로 끝내세요.
New in 0.4.0
시간에 대한 대시보드의 line이나 scatter는 시간 위치에 따라 배치되므로 불규칙한 간격이 그대로 보이고, ORDER BY와 무관하게 시간 순서로 그려집니다. 시간이 NULL인 행은 안내와 함께 제외됩니다. 쿼리가 반환한 측정값이 NULL이면 선이 끊깁니다. area는 균등 간격을 유지하며 그 사실을 알려 줍니다. 계열은 이름별로 색을 유지하고, 모든 차트는 쿼리가 잘렸을 때 그 사실을 알려 줍니다.
카드는 쿼리의 첫 행을 보여 줍니다. 쿼리가 둘 이상의 행을 반환하면 그 사실을 숫자 아래에 알리고, 하나도 반환하지 않으면 —를 보여 줍니다.
카드와 텍스트 패널
카드는 note로 숫자를 설명하고 tone으로 상태 색을 줄 수 있습니다. 같은 행의 카드는 값의 글꼴 크기를 공유합니다. 텍스트 패널은 SQL을 실행하지 않고 제목이나 맥락을 더합니다.
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가지 색상을 쓰고, 현재 테마에 맞춘 음영과 여러 계열을 위한 범례를 제공합니다.
숫자 형식과 변화
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가 뒤따라 무엇과 비교한 것인지 알려 줍니다. 변화는 카드의 쿼리에서 계산하세요.
plot "revenue_total" {
type = "card"
query = query.totals
value = revenue
format = "usd0"
delta = growth
delta_format = "pct1"
note = "vs last week"
}레이아웃
width는 대시보드의 열 12개 중 차트가 차지하는 열 수입니다. 차트는 쓰인 순서대로 왼쪽부터 행을 채우고 다음 차트가 들어가지 않으면 다음 행으로 넘어가므로, 3짜리 카드 네 개가 숫자 행을 만들고 그 아래에 width = 6 차트 두 개가 나란히 놓입니다. 열 12개에 못 미치는 행의 나머지는 비어 있습니다. 카드만 있는 행은 낮은 높이에서 시작하고, 표만 있는 행은 가장 긴 표의 행 수만큼(차트 높이까지) 시작합니다. 텍스트 패널 행은 텍스트에 맞추고, 다른 행은 차트 높이에서 시작합니다. 행 크기 조절 핸들은 마우스를 올리면 나타납니다.
지도
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). 전송되는 것은 어떤 지도 타일을 원하는지뿐이며, 이는 대략 어느 지역을 보고 있는지를 드러낼 뿐 여러분 데이터의 행은 아닙니다. 타일은 일주일 동안 디스크에 캐시됩니다(설정과 앱 데이터 참고). 오프라인이거나 꺼져 있으면 지도는 위도·경도 그리드 위에만 그려집니다. 같은 스위치가 쿼리 결과의 차트 탭에 있는 지도에도 적용됩니다.
필터
필터는 차트를 클릭 가능하게 만들고, 거기서 고른 값이 다른 쿼리를 좁히게 합니다.
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는 이제 선택된 값 변형도 바인딩하므로 첫 클릭 전에 없는 열이 잡힙니다.
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 외에 보간도 없습니다.
히어독
히어독은 여러 줄에 걸친 텍스트를 담습니다. 실제로는 SQL입니다.
sql = <<SQL
SELECT 1
SQL<<뒤의 구분자는 아무 단어나 되며(관례상SQL), 그 줄에서 뒤에 아무것도 올 수 없습니다.- 히어독은 정확히 구분자인 첫 줄에서 끝납니다. 앞뒤 공백은 허용됩니다.
- 닫는 줄의 들여쓰기가 텍스트의 모든 줄에서 제거되므로, SQL을 블록의 들여쓰기에 맞춰 두어도 그 들여쓰기가 따라가지 않습니다.
SQL 규칙
대시보드는 열릴 때, 다시 불러올 때, 저장할 때, 그리고 탭이 복원된 채 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 블록은 경로를 대시보드 폴더 기준으로 명시적으로 해석해 이런 모호함을 피합니다. 절대 경로와 등록된 뷰는 그대로 사용할 수 있습니다.
제한
| 제한 | 동작 |
|---|---|
| 차트당 계열 12개 | 추가 계열은 제외되고, 몇 개였는지 알려 줍니다 |
| 계열당 점 1,500개 | 점을 구간 평균으로 줄여 맞춥니다 |
| 막대 200개 | 추가 막대는 제외됩니다 |
| 원형 조각 8개 | 가장 작은 것들이 하나의 "other" 조각으로 합쳐집니다 |
| 히트맵 열 200개, 행 12개 | 추가 열과 행은 제외됩니다 |
| 히스토그램 구간 5–40개 | 대략 행 수의 제곱근만큼, 각 폭은 1, 2, 2.5 또는 5 × 10의 거듭제곱 |
| 지도 점 20,000개 | 추가 점은 제외되고 그 사실을 알려 줍니다 |
| 타임라인당 레인 12개, 이벤트 1,000개 | 추가 이벤트는 고르게 줄이고 그 사실을 알려 줍니다. 시간을 읽을 수 없는 행은 그리지 않고 셉니다 |
대시보드 검증
ducklocal check는 창을 열지 않고 파일을 검증합니다. 누군가에게 대시보드를 건네기 전에 실행할 단계입니다.
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 가이드에 있습니다.
New in 0.4.0
ducklocal check FILE --restricted --allow-read PATH는 직접 작성하지 않은 대시보드를 제한된 조건에서 검사합니다. 직접 작성하지 않은 SQL 제한하기를 참고하세요.
자주 나오는 메시지
| 메시지 | 해결 방법 |
|---|---|
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 규칙 참고 |
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 가이드에 있습니다.
