---
title: "일반 텍스트 파일로 만드는 로컬 SQL 대시보드 | DuckLocal"
description: "DuckDB 대시보드를 일반 텍스트 .dash 파일로 만드세요. SQL 쿼리, 차트, 카드, 지도, 교차 필터가 내 컴퓨터에서 실행되고, git에서 리뷰할 수 있으며, AI 에이전트가 편집하고 검증할 수 있습니다."
image: https://ducklocal.app/og-image.jpg?v=2
language: ko
---

# 읽고, diff하고, 리뷰할 수 있는 SQL 대시보드

DuckLocal 대시보드는 일반 텍스트 `.dash` 파일입니다. 데이터 소스, DuckDB SQL 쿼리, 그리고 결과를 그리는 플롯으로 이루어집니다. 내 컴퓨터에서 로컬 파일을 대상으로 실행되고, 코드처럼 git에 두며, 직접 쓰거나 AI 에이전트가 쓸 수 있습니다.

BI 서버도, 계정도, 데이터 업로드도 없습니다. macOS, Windows, Linux용 무료 오픈 소스.

- 일반 텍스트 .dash 파일
- 차트, 카드, 지도, 표
- 클릭으로 플롯 간 필터링
- ducklocal check로 검증

## 대시보드는 짧은 파일입니다

`source` 블록은 데이터 파일을 지정하고, `query` 블록은 SQL을 담고, `plot` 블록은 각 결과를 그리는 방법을 정합니다. `filter` 블록을 쓰면 한 플롯을 클릭해 다른 플롯을 좁힐 수 있습니다. 배워야 할 함수나 템플릿은 없고, SQL과 몇 가지 속성뿐입니다.

경로는 `.dash` 파일 기준 상대 경로이므로, 명세와 데이터를 담은 폴더는 어디에 복사해도 동작합니다.

[모든 블록과 속성](https://ducklocal.app/docs/ko/dashboards#blocks)

```hcl
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**정렬 가능한 행, 제목과 메모
[플롯 종류와 옵션 →](https://ducklocal.app/docs/ko/dashboards#plot-types)

## 문서처럼 대시보드 리뷰하기

플롯에 마우스를 올리고 말풍선을 클릭해 바꿀 점을 쓰세요. 예를 들어 *“큰 채널부터 순서대로 정렬해 주세요”*처럼요. 스레드에는 답글을 달고 해결 처리할 수 있으며, 열린 스레드가 있는 플롯에는 개수가 표시됩니다.

AI 에이전트는 `ducklocal comments`로 같은 스레드를 읽습니다. 각 스레드에는 대상 플롯과 파일 안 블록의 줄 번호가 적혀 있습니다. 에이전트는 명세를 수정하고 검증한 뒤 답합니다. 열려 있는 창은 1초 안에 다시 그려지고 **Agent** 표시가 붙은 답글이 나타납니다.

[댓글로 리뷰하기](https://ducklocal.app/docs/ko/dashboards#review-with-comments) · [Claude Dashboards에서 배운 DuckLocal 이야기](https://ducklocal.app/ko/blog/claude-dashboards-ducklocal/)

```bash
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 작업이 활용할 수 있는 종료 코드를 반환합니다.

[대시보드 검증하기](https://ducklocal.app/docs/ko/dashboards#validate-a-dashboard)

- 문법, 이름, 참조 확인
- 각 쿼리의 SQL을 DuckDB로 실행
- 플롯 열을 실제 결과와 대조
- 값을 선택한 상태로 필터 확인
- 행을 반환하지 않는 쿼리 표시

## 데이터는 로컬에, 파일은 어디로든

쿼리는 DuckLocal에 내장된 DuckDB 엔진에서 디스크의 파일이나 DuckDB 데이터베이스를 대상으로 실행됩니다. 폴더를 보내면 상대방은 자기 데이터 사본으로 같은 대시보드를 봅니다. 게시할 것도, 공유할 작업 공간도 없습니다.

> **쿼리 하나에서 시작하나요?** SQL 편집기의 결과는 그 자리에서 차트로 그릴 수 있습니다. 남겨 둘 만한 차트가 모이면 `.dash` 파일을 쓰세요. [결과와 차트 →](https://ducklocal.app/docs/ko/results-and-charts)

## 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](https://ducklocal.app/ko/use-cases/ai-agent-sql/) · [로컬 데이터 분석](https://ducklocal.app/ko/use-cases/local-data-analysis/) · [DuckDB GUI](https://ducklocal.app/ko/use-cases/duckdb-gui/) · [SQL로 CSV 쿼리](https://ducklocal.app/ko/use-cases/query-csv-with-sql/)

## 예제 대시보드 열기

DuckLocal을 다운로드하고, 튜토리얼의 `sales.csv`와 `sales.dash`를 같은 폴더에 저장한 뒤, 대시보드를 창에 놓으세요.

## 링크

- [DuckLocal 다운로드](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [대시보드 가이드 읽기](https://ducklocal.app/docs/ko/dashboards)
- [전체 예제 보기](https://ducklocal.app/docs/ko/dashboards#a-complete-example)

Source: https://ducklocal.app/ko/use-cases/sql-dashboards/
