대시보드는 짧은 파일입니다
source 블록은 데이터 파일을 지정하고, query 블록은 SQL을 담고, plot 블록은 각 결과를 그리는 방법을 정합니다. filter 블록을 쓰면 한 플롯을 클릭해 다른 플롯을 좁힐 수 있습니다. 배워야 할 함수나 템플릿은 없고, SQL과 몇 가지 속성뿐입니다.
경로는 .dash 파일 기준 상대 경로이므로, 명세와 데이터를 담은 폴더는 어디에 복사해도 동작합니다.
source "orders" { path = "orders.csv" } query "revenue" { sql = <<SQL SELECT channel, sum(amount) AS total FROM orders GROUP BY channel ORDER BY total DESC SQL } plot "revenue" { type = "bar" query = query.revenue x = channel y = total }
대시보드에 필요한 플롯
표준 차트, 숫자, 지도를 12열 그리드에 배치합니다.
- line · area시계열, 플롯당 최대 12개 계열
- bar · stacked_bar순위와 구성 비율, 합계 포함
- scatter · histogram상관관계와 분포
- heatmap요일 × 시간, 지역 × 월
- map위도·경도의 점, 크기와 색 지정 가능
- timeline실제 시간 간격으로 레인에 놓이는 이벤트
- card숫자 하나와 그 변화, 좋은지 나쁜지까지
- table · text정렬 가능한 행, 제목과 메모
문서처럼 대시보드 리뷰하기
플롯에 마우스를 올리고 말풍선을 클릭해 바꿀 점을 쓰세요. 예를 들어 “큰 채널부터 순서대로 정렬해 주세요”처럼요. 스레드에는 답글을 달고 해결 처리할 수 있으며, 열린 스레드가 있는 플롯에는 개수가 표시됩니다.
AI 에이전트는 ducklocal comments로 같은 스레드를 읽습니다. 각 스레드에는 대상 플롯과 파일 안 블록의 줄 번호가 적혀 있습니다. 에이전트는 명세를 수정하고 검증한 뒤 답합니다. 열려 있는 창은 1초 안에 다시 그려지고 Agent 표시가 붙은 답글이 나타납니다.
$ ducklocal comments sales.dash {"open":1, "threads":[{"id":"c1", "plot":"revenue_by_channel", "plot_lines":[68,75], ...}]} $ ducklocal check sales.dash $ ducklocal comments sales.dash --reply c1 \ --text "Sorted by revenue, descending" --resolve
누가 열기 전에 먼저 검증
ducklocal check는 파일을 파싱하고, 모든 참조를 해석하고, 모든 쿼리를 읽기 전용으로 실행합니다. 그런 다음 각 플롯의 열이 실제 결과에 있는지 확인하므로, 오타나 실패하는 형 변환, 아무것도 일치하지 않는 glob을 회의가 아니라 터미널에서 잡아냅니다.
모든 문제를 한 번에, 하나당 file:line: message 한 줄로 보여 주며, 스크립트나 CI 작업이 활용할 수 있는 종료 코드를 반환합니다.
- 문법, 이름, 참조 확인
- 각 쿼리의 SQL을 DuckDB로 실행
- 플롯 열을 실제 결과와 대조
- 값을 선택한 상태로 필터 확인
- 행을 반환하지 않는 쿼리 표시
데이터는 로컬에, 파일은 어디로든
쿼리는 DuckLocal에 내장된 DuckDB 엔진에서 디스크의 파일이나 DuckDB 데이터베이스를 대상으로 실행됩니다. 폴더를 보내면 상대방은 자기 데이터 사본으로 같은 대시보드를 봅니다. 게시할 것도, 공유할 작업 공간도 없습니다.
SQL 대시보드에 관한 질문
- .dash 파일이 무엇인가요?
- 대시보드를 블록으로 선언하는 일반 텍스트 파일입니다.
source는 데이터 파일을 지정하고,query는 DuckDB SQL 문장 하나를 담고,plot은 결과를 그리고,filter는 한 플롯을 클릭해 다른 플롯을 좁힙니다. 코드를 쓸 필요가 없습니다. - 대시보드에 서버나 BI 계정이 필요한가요?
- 아니요. DuckLocal이 파일을 열고 앱 안의 DuckDB 엔진으로 내 컴퓨터에서 쿼리를 실행합니다. 데이터 파일은 원래 자리에 그대로 있습니다.
- 어떤 차트를 쓸 수 있나요?
- 선, 막대, 누적 막대, 영역, 산점도, 원형, 히트맵, 히스토그램, 지도, 타임라인 플롯에 더해 표, 변화 표시가 있는 숫자 카드, 텍스트 패널이 있으며 12열 그리드에 배치됩니다.
- AI 에이전트가 대시보드를 만들거나 바꿀 수 있나요?
- 네. 에이전트가 .dash 파일을 쓰거나 편집하고,
ducklocal check로 모든 쿼리가 실행되고 모든 플롯의 열이 있는지 확인하며,ducklocal comments로 리뷰 댓글에 답합니다. 열려 있는 창은 1초 안에 다시 그려집니다. - 대시보드를 git으로 관리할 수 있나요?
- 네. .dash 파일은 짧은 일반 텍스트라서 코드처럼 diff하고 리뷰할 수 있습니다. 리뷰 댓글은 별도의
NAME.dash.comments.json파일에 저장되므로 버전 관리에서 제외할 수 있습니다.
관련 항목: AI 에이전트를 위한 SQL · 로컬 데이터 분석 · DuckDB GUI · SQL로 CSV 쿼리
예제 대시보드 열기
DuckLocal을 다운로드하고, 튜토리얼의 sales.csv와 sales.dash를 같은 폴더에 저장한 뒤, 대시보드를 창에 놓으세요.