# 처음 10분

> 샘플 CSV로 진행하는 10분 DuckLocal 튜토리얼입니다. SQL로 쿼리하고, 결과를 차트로 그리고, 내보내고, 같은 질문을 CLI에서 실행해 봅니다.

Source: https://ducklocal.app/docs/ko/tutorial

안내 투어입니다. 작은 매출 파일을 열고, 몇 가지 쿼리를 실행하고, 답을 차트로
그리고, 결과를 내보냅니다. DuckLocal이 설치되어 있다고 가정합니다. 아직이라면
[시작하기](getting-started.md)부터 보세요.

## 1. 샘플 파일 받기 {#sample-file}

[sales.csv](https://ducklocal.app/docs/samples/sales.csv)를 내려받으세요. 224행에 걸친 2주 분량의 가상
주문 데이터가 들어 있습니다. 터미널에서 받을 수도 있습니다:

```bash
curl -LO https://ducklocal.app/docs/samples/sales.csv
```

열은 다섯 개입니다:

| 열 | 유형 | 예시 |
| --- | --- | --- |
| `date` | DATE | `2026-09-01` |
| `channel` | VARCHAR | `Web`, `Mobile app`, `Store`, `Phone` |
| `region` | VARCHAR | `North`, `South`, `East`, `West` |
| `orders` | BIGINT | `72` |
| `revenue` | DOUBLE | `4181.04` |

이런 정보를 DuckLocal에 알려 줄 필요는 없습니다. DuckDB가 헤더를 읽고 유형을
스스로 추론합니다.

## 2. 파일 열기

`sales.csv`를 DuckLocal 창으로 끌어다 놓습니다. 또는 **파일 열기…**를 클릭하거나,
[명령을 추가](getting-started.md#add-command)했다면 `ducklocal sales.csv`를
실행합니다.

알림에 **뷰 sales를 만들었습니다.**가 표시됩니다. 사이드바의 **로컬 파일**에
`sales`가 224행과 함께 나열되고, 펼치면 열과 각 열의 유형을 볼 수 있습니다.

## 3. 행 살펴보기

사이드바에서 `sales` 옆의 재생 버튼을 클릭합니다. 에디터에
`SELECT * … LIMIT 100`이 채워지면 **⌘↵**를 눌러 실행합니다.

에디터 아래 그리드에 행이 표시됩니다. 위쪽의 필터 상자도 써 보세요. `Store`를
입력하고 Enter를 누르면 그것이 들어 있는 행만 남습니다. 필터는 이미 불러온
행에만 동작하며 쿼리를 다시 실행하지 않습니다.

## 4. 질문하기

SQL을 다음으로 바꾸고 **⌘↵**를 누릅니다:

```sql
SELECT channel, round(sum(revenue), 2) AS revenue
FROM sales
GROUP BY channel
ORDER BY revenue DESC;
```

| channel | revenue |
| --- | --- |
| Mobile app | 290549.76 |
| Web | 289544.8 |
| Store | 240067.6 |
| Phone | 82511.2 |

이제 결과 패널을 **결과**에서 **차트**로 전환합니다. 첫 번째 열이 텍스트이므로
채널마다 막대가 하나씩 그려지고, 크기는 첫 번째 숫자 열을 따릅니다.

::: tip 자동 완성
입력하는 동안 에디터는 사이드바의 테이블 이름과 열 이름을 먼저 제안하고, 그다음
DuckDB 함수와 SQL 키워드를 제안합니다. `rev`를 입력하면 `revenue`가 첫 번째
제안입니다.
:::

## 5. 추세 차트 그리기

차트는 쿼리가 반환한 행을 그대로 사용해 그려지므로, 그리고 싶은 모양으로 결과를
만들면 됩니다. 채널마다 열을 하나씩 두면 채널마다 선이 하나씩 생깁니다:

```sql
SELECT
  date,
  round(sum(revenue) FILTER (WHERE channel = 'Web'), 2)        AS web,
  round(sum(revenue) FILTER (WHERE channel = 'Mobile app'), 2) AS mobile,
  round(sum(revenue) FILTER (WHERE channel = 'Store'), 2)      AS store
FROM sales
GROUP BY date
ORDER BY date;
```

`FILTER (WHERE …)`는 조건에 맞는 행만 집계합니다(DuckDB 문법).

첫 번째 열이 날짜이면 **차트**는 시간에 따른 영역 차트를 그리고, 숫자 열마다
계열이 하나씩 생깁니다. 규칙과 제한은 [결과와 차트](results-and-charts.md)에
정리되어 있습니다.

## 6. 답 내보내기

**내보내기는 기존 파일을 묻지 않고 덮어씁니다.** 추세가 결과 패널에 있는 상태에서
**CSV 내보내기**를 클릭합니다. 대화 상자가 `~/Desktop/export.csv`를 제안하니
원하면 경로를 바꾸고 확인하세요.

내보내기는 쿼리를 다시 실행하므로 파일에는 그리드에 보이는 부분만이 아니라 전체
결과가 들어갑니다.

## 7. 내일 다시 찾기

사이드바의 **기록** 탭을 엽니다. 실행한 모든 쿼리가 실패한 것까지 포함해 남아
있습니다. 항목을 클릭하면 에디터의 현재 내용이 그 쿼리로 바뀝니다.

DuckLocal을 종료했다가 다시 실행해 보세요. `sales`는 여전히 **로컬 파일**에
있습니다. 연 파일은 경로로 기억되어 실행할 때마다 다시 읽히므로, CSV를 수정하면
다음에 쿼리할 때 반영됩니다.

## 8. 보너스: 같은 질문을 터미널에서

`ducklocal` 명령을 추가했다면 CLI가 창을 열지 않고 답합니다. 스크립트와 AI
에이전트에 유용합니다:

```bash
ducklocal query --format md --sql "
  SELECT channel, round(sum(revenue), 2) AS revenue
  FROM 'sales.csv' GROUP BY channel ORDER BY revenue DESC"
```

`--format md`를 빼면 구조화 JSON이 나옵니다. [CLI 가이드](cli.md)와 공식
에이전트 스킬(AI 코딩 어시스턴트가 호출할 수 있는 스킬 패키지)부터 시작하세요.

## 다음

- 실제 데이터로 해 보기: HTTPS로 350만 건의 택시 운행 데이터를 쿼리 — [예제: NYC 택시 운행](example-nyc-taxi.md)
- 내 파일과 폴더를 DuckLocal로 열기 — [데이터 소스](data-sources.md)
- S3 호환 스토리지의 파일 쿼리하기 — [S3와 httpfs](s3.md)
- 저장한 쿼리로 대시보드 만들기 — [대시보드(.dash)](dashboards.md)
