---
title: DuckLocal — 로컬 파일을 SQL로 다루는 DuckDB 데스크톱 앱
description: CSV, Parquet, JSON, Excel 파일을 DuckDB SQL로 로컬에서 쿼리합니다. 서버도, 업로드도, 계정도, 텔레메트리도 필요 없습니다.
image: https://ducklocal.app/og-image.jpg?v=2
language: ko
---

# DuckLocal

CSV, Parquet, JSON, Excel 파일을 컴퓨터에 있는 그 자리에서 DuckDB로 쿼리합니다. 서버도, 업로드도, 계정도 필요 없습니다.

DuckLocal은 Mac, Windows, Linux를 지원하는 무료 오픈 소스 데스크톱 앱이며 Apache-2.0으로 배포됩니다.

## 에이전트는 터미널에, 데이터는 DuckLocal에

에이전트가 `.dash` 파일을 작성합니다. DuckLocal에서 검토하고 차트 위에 바로 주석을 남기세요.

- `ducklocal schema`는 모든 파일, 테이블, 열을 나열합니다. `--stats`를 붙이면 열별 정확한 통계도 나옵니다.
- `ducklocal query`는 SQL 문 하나를 받아 범위가 제한된 JSON을 반환합니다. 결과가 잘린 경우에도 그 사실이 표시됩니다.
- `ducklocal open`은 쿼리나 대시보드를 열려 있는 창으로 보냅니다. `--state`로 지금 보이는 내용을 다시 읽어옵니다.
- `ducklocal check`는 `.dash` 파일을 보기 전에 검증합니다. 대시보드는 코드처럼 diff하고 커밋할 수 있습니다.
- `ducklocal comments`를 쓰면 에이전트가 주석을 남긴 차트를 수정하고, 답글을 달고, 스레드를 해결합니다.
- `ducklocal presence`는 에이전트가 어떤 차트를 읽거나 편집하는지 창에 표시합니다.

```bash
ducklocal schema ./data/
ducklocal query --sql "SELECT count(*) FROM 'sales.csv'"
```

세 단계로 에이전트를 연결합니다:

1. DuckLocal에서 **명령줄 & AI…**를 열고 **명령 설치**를 클릭하면 `ducklocal`이 PATH에 추가됩니다.
2. **Claude Code에 추가**를 클릭하면 공식 스킬이 설치됩니다. Codex나 Cursor에서는 **브리프 복사**를 클릭해 붙여 넣으세요.
3. 터미널에서 에이전트에 작업을 맡기고, 결과를 DuckLocal에서 검토하며 주석을 남기세요.

홈페이지의 데모는 튜토리얼의 224행짜리 `sales.csv` 샘플에서 계산됩니다. 웹사이트는 AI 요청을 보내지 않으며, 주석을 게시해도 에이전트가 자동으로 실행되지 않습니다.

[AI 에이전트를 위한 SQL](https://ducklocal.app/ko/use-cases/ai-agent-sql/), [CLI 레퍼런스](https://ducklocal.app/docs/ko/cli), [대시보드 가이드](https://ducklocal.app/docs/ko/dashboards)를 읽어 보세요.

## 파일에서 답까지

1. **파일을 넣습니다.** CSV, 스프레드시트, 폴더 전체를 끌어다 놓습니다. 가져오기 단계가 없습니다.
2. **이미 테이블입니다.** `sales.csv`는 테이블 `sales`가 되고, 열은 사이드바에 표시됩니다. 파일은 복사되거나 변경되지 않습니다.
3. **SQL로 질문합니다.** ⌘↵를 누르면 답이 나옵니다. 그다음 차트로 만들거나 CSV, Parquet로 저장하세요.

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

DuckLocal은 CSV, TSV, Parquet, JSON, NDJSON, Excel과 OpenDocument 스프레드시트, DuckDB 데이터베이스, 폴더 전체, S3 스토리지를 모두 있는 자리에서 엽니다.

## 첫 번째 답 이후

- 쿼리를 프로파일링해 어느 단계에서 시간이 걸렸는지 확인합니다.
- 결과의 모든 열에서 NULL, 고유값, 범위를 확인합니다.
- DuckDB나 SQLite 데이터베이스를 더 연결하고, 사이드바에서 확장 기능을 관리합니다.
- Mac에서는 Finder에서 Parquet, DuckDB 파일을 열거나 Quick Look으로 미리 볼 수 있습니다.

## 데이터는 당신의 것입니다

- 파일은 있는 자리에서 읽히며, 복사되거나 업로드되지 않습니다.
- 계정도, 텔레메트리도, 클라우드 서비스도 없습니다.
- 직접 켜기 전에는 아무것도 외부로 나가지 않습니다.
- Apache-2.0 오픈 소스이므로 모든 코드를 직접 읽을 수 있습니다.

## 자주 묻는 질문

### DuckLocal이란 무엇인가요?

컴퓨터에 있는 데이터 파일을 SQL로 쿼리하는 무료 오픈 소스 데스크톱 앱입니다. 앱 안에서 DuckDB가 실행되므로, 넣은 파일이 곧 쿼리할 수 있는 테이블이 됩니다.

### DuckLocal이 제 데이터를 업로드하나요?

아니요. 파일은 있는 자리에서 읽히며 복사되거나, 업로드되거나, 변경되지 않습니다. 계정도 텔레메트리도 없습니다.

### 어떤 파일 형식을 열 수 있나요?

CSV, TSV, Parquet, JSON, NDJSON, Excel과 OpenDocument 스프레드시트, DuckDB 데이터베이스, 폴더 전체, 그리고 Amazon S3 또는 S3 호환 스토리지의 파일을 엽니다.

### 어떤 시스템에서 실행되나요?

Apple silicon의 macOS 12 이상, 64비트 Windows 10 이상, glibc 2.35 이상의 x86_64 Linux입니다.

### 데이터는 얼마나 커도 되나요?

DuckDB는 파일을 앱에 먼저 불러오지 않고 직접 쿼리합니다. 결과 그리드에는 최대 100,000행이 표시되고, 내보내기에서는 결과 전체가 기록됩니다.

### Claude Code나 Codex 같은 AI 에이전트도 쓸 수 있나요?

네. ducklocal 명령은 터미널에서 SQL을 실행하고 JSON을 출력합니다. 공식 스킬은 에이전트가 쿼리 전에 스키마를 확인하도록 가르칩니다.

## 링크

- [DuckLocal 다운로드](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [시작하기](https://ducklocal.app/docs/ko/getting-started)
- [10분 튜토리얼](https://ducklocal.app/docs/ko/tutorial)
- [로컬 데이터 분석](https://ducklocal.app/ko/use-cases/local-data-analysis/)
- [DuckDB GUI](https://ducklocal.app/ko/use-cases/duckdb-gui/)
- [Parquet 뷰어](https://ducklocal.app/ko/use-cases/parquet-viewer/)
- [SQL로 CSV 쿼리](https://ducklocal.app/ko/use-cases/query-csv-with-sql/)
- [SQL로 Excel 쿼리](https://ducklocal.app/ko/use-cases/query-excel-with-sql/)
- [SQL로 JSON 쿼리](https://ducklocal.app/ko/use-cases/query-json-with-sql/)
- [SQL 대시보드](https://ducklocal.app/ko/use-cases/sql-dashboards/)
- [DuckLocal vs DBeaver](https://ducklocal.app/ko/compare/ducklocal-vs-dbeaver/)
- [블로그](https://ducklocal.app/ko/blog/)
- [문서](https://ducklocal.app/docs/ko/)
- [소스 코드](https://github.com/JetSquirrel/DuckLocal)
- [中文](https://ducklocal.app/zh/)
- [日本語](https://ducklocal.app/ja/)

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