# 데이터 소스

> CSV, Parquet, JSON, Excel 파일을 DuckDB SQL로 로컬에서 쿼리합니다. 폴더와 glob을 열고, 데이터베이스를 연결하고, 데이터를 내 컴퓨터에 보관합니다.

Source: https://ducklocal.app/docs/ko/data-sources

DuckLocal은 파일을 인메모리 DuckDB 연결의 뷰로 만들고, 데이터베이스 파일을 열었다면 그
파일의 뷰로 만듭니다. 다른 데이터베이스를 그 옆에 둘 수도 있습니다. 설정할 것은 없습니다.
파일에서 SQL, 차트, 내보내기로 이어지는 간결한 경로는 [로컬 데이터 분석 워크플로](https://ducklocal.app/use-cases/local-data-analysis/)를 참고하세요.

## 데이터를 여는 방법

모두 같은 경로 해석 규칙을 거칩니다:

1. 명령줄의 경로 — `ducklocal ./logs/ billing.parquet`
2. 제목 표시줄의 **열기** 메뉴: **파일 열기**, **폴더 열기**, 또는 **경로나 glob 입력**.
   마지막 항목은 입력한 경로나 네이티브 선택기에서 고른 경로를 위해
   **데이터 열기** 대화상자를 엽니다
3. 창 어디든 파일이나 폴더를 끌어다 놓기
4. Mac에서는 Finder가 DuckLocal에 넘기는 파일 — [Finder에서 열기](#open-from-finder) 참고

열려 있는 데이터베이스를 바꾸지 않고 옆에 추가하려면
**열기 → 데이터베이스 연결…**을 사용하세요 — [연결된 데이터베이스](#attached-databases)를 참고하세요.

macOS에서는 Finder에서 Parquet과 DuckDB 파일을 더블클릭해 열거나, 스페이스 바를 눌러
DuckLocal을 실행하지 않고 Quick Look으로 Parquet, DuckDB, CSV, TSV, JSON Lines 파일의
처음 몇 행을 미리 볼 수 있습니다.

## 지원하는 파일 형식 {#supported-file-formats}

확장자는 대소문자를 구분하지 않고 일치합니다.

| 확장자 | 읽는 방법 |
| --- | --- |
| `.csv`, `.tsv`, `.txt` | `read_csv_auto` 뷰 |
| `.parquet` | `read_parquet` 뷰 |
| `.json`, `.ndjson`, `.jsonl` | `read_json_auto` 뷰 |
| `.xlsx`, `.xls`, `.xlsb`, `.ods` | 시트마다 테이블로 가져오기 |

`.json.gz`, `.csv.gz` 같은 gzip 텍스트도 데이터 파일로 취급되며, `schema`, `source`
블록과 파일을 연결할 때 처리됩니다. `logs.json.gz`는 `logs`라는 이름의 뷰가 됩니다.
0.4.0 이전의 `ducklocal schema`는 그런 파일을 데이터베이스로 시도했습니다. 이전 버전에서는
SQL에서 `read_json` 또는 `read_csv`로 읽으세요.

그 밖의 것은 데이터 파일이 아닙니다 — [데이터베이스 파일](#database-files)을 참고하세요.

워크북은 뷰가 아니라 **테이블**이 되는 유일한 형식이며 **모든 시트**를 가져옵니다. 첫
시트는 확장자를 뺀 파일 이름을 이름으로 쓰고, 나머지는
`{stem}_{sheet name}`이라는 이름이 됩니다. 빈 시트는 건너뜁니다. 열 타입은 셀에서
추론합니다 — 정수는 `BIGINT`, 정수와 부동 소수점이 섞이면 `DOUBLE`, 날짜는 `TIMESTAMP`,
섞여 있거나 인식할 수 없는 값은 `VARCHAR`가 되고, 빈 셀은 `NULL`로 가져옵니다.

## 폴더와 패턴 {#folders-and-patterns}

**디렉터리**는 재귀적으로 순회하며, 안의 모든 데이터 파일이 뷰가 됩니다. 순회에는 두 가지
규칙이 적용됩니다:

- 숨김 항목(`.`으로 시작하는 이름)은 건너뛰고, 그 하위 트리로 내려가지 않습니다.
- 심볼릭 링크는 따라가지 않습니다. 트리 위쪽으로 이어지는 링크를 따라가면 끝나지 않으며,
  링크된 디렉터리는 보통 실제로 있는 위치에서 순회됩니다.

파일은 정렬된 순서로 연결되므로 같은 폴더는 항상 같은 워크스페이스를 만듭니다.

**패턴**에는 `*`(임의 길이의 문자)와 `?`(정확히 한 문자)를 쓸 수 있습니다. 일치는 경로
구성 요소마다 파일 시스템을 대상으로 이루어지므로, 패턴이 디렉터리를 가로지를 수 있습니다:

```bash
ducklocal './data/2026-0*/*.parquet'
```

이스케이프 문자는 없습니다. `**`는 특별하지 않습니다 — 단일 `*`처럼 동작하며 재귀하지
않습니다. 디렉터리에 일치하는 패턴은 그 디렉터리를 건너뜁니다. 연결되는 것은 파일뿐입니다.
여기서도 숨김 항목은 건너뜁니다.

따옴표로 감싸지 않은 패턴은 DuckLocal이 보기 전에 셸이 확장합니다. 그래도 괜찮습니다.
패턴을 따옴표로 감쌀 때는 DuckLocal이 확장하기를 원할 때뿐입니다 — 예를 들어 셸이 일치하는
항목을 찾지 못해 오류를 낼 경우입니다.

## 한 번에 많은 CSV 파일 {#many-csv-files-at-once}

DuckLocal이 연결하는 각 파일은 자체적으로 스니핑한 스키마를 가진 별도 뷰가 되므로, 서로
맞지 않는 두 CSV가 서로를 깨뜨리지 않습니다. 함정은 하나의 SQL 읽기가 여러 파일에 걸칠 때
나타납니다:

```sql
SELECT * FROM read_csv('data/*.csv', union_by_name = true)
```

- **타입 스니핑은 파일마다 다를 수 있습니다.** 리더는 샘플에서 열의 타입을 추론합니다.
  어디서나 숫자인 열이 한 파일에서 `'NULL'` 문자열을 하나 포함하면 전체 읽기가 변환
  오류로 실패하며, `SELECT` 목록의 캐스트는 너무 늦습니다 — 읽기 자체가 오류를 냅니다.
  대신 모든 열을 텍스트로 읽고 SQL에서 캐스트하세요:

  ```sql
  SELECT try_cast(amount AS DOUBLE) AS amount
  FROM read_csv('data/*.csv', union_by_name = true, all_varchar = true)
  ```

  `union_by_name = true`는 열 집합이 다른 파일도 허용합니다.
- **문자열 `'NULL'`은 `NULL`이 아닙니다.** CSV의 리터럴 `'NULL'`(또는 `'N/A'`,
  `'null'`)은 그냥 텍스트이므로 `WHERE amount IS NOT NULL`로 걸러지지 않습니다.
  `NULLIF(amount, 'NULL')` 또는 `WHERE amount <> 'NULL'`을 사용하세요.

두 수정은 함께 쓸 수 있습니다: `try_cast(NULLIF(amount, 'NULL') AS DOUBLE)`.

## 데이터베이스 파일 {#database-files}

DuckLocal은 한 번에 하나의 **기본 데이터베이스**를 가집니다: 인메모리이거나, 열어 둔 DuckDB
파일입니다. 데이터 파일은 기본 데이터베이스의 뷰가 됩니다.
[다른 데이터베이스를 그 옆에 연결](#attached-databases)할 수도 있습니다.

**존재하는** 경로이면서 데이터 파일이 아닌 것은 뷰로 연결되지 않고 대신 기본 데이터베이스로
열립니다. 확장자는 중요하지 않습니다: `.db`, `.duckdb`, 심지어 `.md` 경로도 데이터베이스로
취급되며, 실제로 열 수 있는지는 DuckDB가 판단합니다.

몇 가지 짚어 둘 결과가 있습니다:

- **새 데이터베이스는 데이터 열기 대화상자에서만 만들어집니다.** 아직 없는 `.duckdb`로
  끝나는 경로를 입력하면 DuckLocal이 없는 상위 폴더와 함께 데이터베이스를 만듭니다.
  그 밖의 곳 — 명령줄, 선택기, 드롭, Finder — 에서는 존재하지 않는 경로가
  `File not found`로 보고됩니다.
- **데이터베이스를 열면 기본 데이터베이스가 바뀝니다.** 등록한 파일과 연결한 데이터베이스는
  새 연결에 다시 연결됩니다. S3 자격 증명은 그렇지 않으므로 S3을 다시 설정하세요.
- **파일을 열 수 없으면** DuckLocal이 이유를 알려 줍니다
  ([아래](#when-a-database-will-not-open)). 시작 시에는 시작에 실패하는 대신 인메모리
  워크스페이스로 폴백합니다. 실행 중이라면 가지고 있던 워크스페이스가 그대로 유지됩니다.
- **이미 기본 데이터베이스 옆에 연결된 파일**은 먼저 연결이 해제된 뒤 기본 데이터베이스로
  열립니다. 그 열기가 실패하면 연결이 되돌아옵니다. 이미 기본 데이터베이스인 파일을 열면
  그대로 재사용합니다.

데이터베이스 파일이 열려 있는 동안 데이터 파일을 연결하면 **그 뷰가 해당 데이터베이스 파일에
기록됩니다** — 세션에만 있는 것이 아니라 그곳에 유지됩니다.

### 데이터베이스가 열리지 않을 때 {#when-a-database-will-not-open}

DuckDB가 파일을 거부하면 DuckLocal이 파일의 처음 바이트를 직접 읽고, 그 바이트가 실패를
설명하는 경우 DuckDB 자체 메시지 위에 이유와 해결 방법을 표시합니다. 정확한 오류를 위해
DuckDB 메시지는 아래에 남습니다. 설명은 인터페이스 언어로 표시됩니다.

| 파일의 정체 | DuckLocal이 알려 주는 내용 |
| --- | --- |
| DuckLocal에 내장된 것보다 **최신 DuckDB**가 쓴 DuckDB 파일 | 두 버전, 그리고 최신 DuckDB에서 실행해 파일을 DuckLocal이 읽을 수 있는 형식으로 복사하는 SQL(아래) |
| **v0.9 이하**의 DuckDB 파일 | 그 파일을 쓴 DuckDB에서 `EXPORT DATABASE 'dir'`을 실행한 뒤 DuckLocal에서 `IMPORT DATABASE 'dir'` 실행 |
| **SQLite** 데이터베이스 | DuckDB 파일이 아닙니다. 대신 연결하세요 — [데이터베이스 연결…](#attached-databases) 또는 `INSTALL sqlite; ATTACH '…' (TYPE sqlite);` |
| **DuckDB 파일이 아닌** 다른 것 | 대신 CSV, Parquet, JSON, Excel 파일을 데이터 파일로 여세요 |

최신 DuckDB의 파일이라면 메시지에 파일 경로와 DuckLocal의 DuckDB 버전이 채워집니다.
파일을 만든 DuckDB에서 실행한 뒤 `compat.duckdb`를 여세요:

```sql
ATTACH '/path/to/file.duckdb' AS src (READ_ONLY);
ATTACH 'compat.duckdb' AS dst (STORAGE_VERSION 'v2.0.0');
COPY FROM DATABASE src TO dst;
```

DuckDB v1.2 이전에 작성된 파일은 어떤 릴리스가 만들었는지 기록하지 않습니다. 그 밖의
실패 — 다른 프로그램이 잠근 파일, 읽을 수 없는 파일 — 는 DuckDB 메시지만 표시합니다.
[문제 해결](troubleshooting.md#opening-a-database)을 참고하세요.

### 어떤 DuckDB가 데이터베이스를 읽을 수 있는가 {#storage-version}

데이터베이스 파일을 열면 상태 표시줄에 그 경로가 표시됩니다. 그 위에 마우스를 올리면 파일의
저장 형식(이를 읽을 수 있는 가장 오래된 DuckDB, 예를 들어
**저장 형식: DuckDB v1.0.0+에서 읽기 가능**)과, 파일에 기록이 있으면 그것을 만든 릴리스
(**DuckDB v1.4.3에서 생성**)가 표시됩니다. 더 오래된 DuckDB를 쓰는 사람에게 파일을 넘기기
전에 이것을 확인하세요.

DuckLocal은 DuckDB 2.0을 실행하지만, 만들어진 데이터베이스 파일은 DuckDB 1.x가 쓴
형식(**DuckDB v1.0.0+에서 읽기 가능**)으로 기록되므로 DuckDB 1.x의 duckdb CLI, Python,
DBeaver에서도 열립니다. 다른 프로그램이 DuckDB 2.0 자체 형식(**v2.0.0+**)으로 쓴 파일도
열리며, 그 형식을 그대로 유지합니다. 1.x에서는 읽을 수 없습니다.

## 연결된 데이터베이스 {#attached-databases}

기본 데이터베이스 옆에 다른 DuckDB 또는 SQLite 파일을 연결해 그것들을 함께 쿼리할 수
있습니다 — 예를 들어 오늘의 데이터 옆에 스냅숏을 두는 경우입니다.

1. 제목 표시줄의 **열기** 메뉴를 열고 **데이터베이스 연결…**을 고릅니다.
2. 경로를 입력하거나 **찾아보기**를 클릭해 파일을 고릅니다.
3. 파일을 변경할 생각이 아니라면 **읽기 전용**을 체크한 채로 둡니다. 기본값으로
   체크되어 있습니다.
4. **연결**을 클릭합니다.

데이터베이스는 파일 이름에서 **별칭**을 얻고, 그 테이블을 `alias.table`(또는
`alias.schema.table`)로 쿼리합니다:

```sql
-- snap-2026-10-01.duckdb attached as snap_2026_10_01
SELECT t.id, t.amount, s.amount AS amount_last_week
FROM orders t
JOIN snap_2026_10_01.orders s USING (id);
```

별칭을 만드는 방법:

- 확장자를 뺀 파일 이름에서 ASCII 영문자나 숫자가 아닌 모든 문자를 `_`로 바꿉니다.
- 영문자로 시작하지 않으면 앞에 `db_`를 붙입니다:
  `2026-10 logs.duckdb`는 `db_2026_10_logs`가 됩니다.
- 이름이 이미 쓰이고 있으면 카운터를 붙입니다: `snap`, 그다음 `snap_2`. `main`은
  절대 쓰지 않습니다.
- 나중에 같은 파일을 다시 연결하면 이전에 가졌던 별칭을 돌려주므로, 그에 맞춰 작성한
  SQL이 계속 동작합니다.

자세한 내용:

- **SQLite 파일**은 내용으로 식별되며 DuckDB의 `sqlite` 확장 기능을 통해 연결됩니다.
- **읽기 전용 체크를 해제하면** 파일을 쓰기용으로 연결합니다. 존재하지 않는 DuckDB
  경로는 그때 새 빈 데이터베이스로 만들어집니다. 읽기 전용이면 대신 연결이 실패합니다.
- **같은 파일은 두 번 연결되지 않습니다.** 이미 열려 있는 파일 — 기본 데이터베이스이든
  연결된 것이든 — 을 연결하려 하면 *이 데이터베이스는 이미 열려 있습니다: …*라고
  표시됩니다.

### 사이드바에서 {#in-the-sidebar}

모든 데이터베이스가 스키마 트리에 나타납니다. 기본 데이터베이스와 연결된 데이터베이스,
빈 데이터베이스까지 포함해서요. 데이터베이스는 해당되는 경우 이름 옆에 **읽기 전용**
또는 **sqlite**를 표시하고, 툴팁에 그 파일을 보여 줍니다.

데이터베이스를 마우스 오른쪽 버튼으로 클릭하면:

- **기본 데이터베이스로 사용** — `USE`를 실행하므로 데이터베이스 이름이 없는 테이블
  이름은 그곳에서 해석됩니다. 상태 표시줄에 현재 해석 위치가 표시됩니다.
- **데이터베이스 연결 해제** — 연결을 해제하고 기억에서 지우므로 다음에 다시 나타나지
  않습니다. 기본 데이터베이스였다면 세션이 먼저 기본 데이터베이스로 돌아갑니다.
  파일 자체는 그대로입니다.

그 메뉴의 나머지는
[스키마 브라우저와 기록](schema-and-history.md)에서 설명합니다.

### 연결을 넘어 유지됨 {#kept-across-connections}

연결된 데이터베이스는 별칭과 읽기 전용 설정과 함께 DuckLocal 자체의 기록 데이터베이스에
저장되고, 새 연결마다 다시 연결됩니다: 다음 실행 시, 다른 데이터베이스를 연 뒤, 그리고
**새 인메모리 데이터베이스** 이후에요.

- 파일이 **없는** 데이터베이스는 조용히 건너뜁니다. 등록은 유지되므로 파일이 돌아오면
  다시 나타납니다 — DuckLocal이 그 자리에 빈 데이터베이스를 만드는 일은 없습니다.
- **이미 열려 있는** 데이터베이스는 기본 데이터베이스이든 아니든 두 번째로 연결되지
  않습니다.
- 새 기본 데이터베이스에 그 별칭의 데이터베이스가 이미 있으면 DuckLocal은
  *연결할 수 없습니다 …: 이름 …이(가) 열려 있는 데이터베이스에서 사용 중입니다.*라고
  표시합니다.

## Finder에서 열기 {#open-from-finder}

Mac에서는 Finder가 파일을 DuckLocal에 직접 넘길 수 있습니다:

| 파일 | 더블클릭 | 연결 프로그램, 또는 Dock 아이콘에 드롭 |
| --- | --- | --- |
| `.parquet` | DuckLocal에서 열림 | 예 |
| `.duckdb`, `.ddb` | DuckLocal에서 열림 | 예 |
| `.dash` | DuckLocal에서 열림 | 예 |
| `.csv`, `.tsv`, `.json`, `.jsonl`, `.ndjson`, `.xlsx`, `.xls` | 이미 그것을 여는 앱(Numbers, Excel, 텍스트 편집기)에 그대로 남음 | 예 |

DuckLocal은 Mac에서 다른 앱이 가져가지 않은 형식에 대해서만 자신을 기본 앱으로
등록합니다. 다른 앱이 이미 Parquet이나 DuckDB 파일을 가져갔다면 **연결 프로그램**에서
DuckLocal을 고르거나, Finder의 **정보 가져오기 → 다음으로 열기 → 모두 변경…**을 사용해
기본 앱으로 만드세요.

Finder에서 온 파일은 창에 드롭한 것과 똑같이 처리됩니다: 데이터 파일은 현재 워크스페이스의
뷰가 되고, 데이터베이스 파일은 기본 데이터베이스로 열리며, `.dash` 파일은
[대시보드](dashboards.md) 탭으로 열립니다. DuckLocal이 실행 중이 아니면 먼저 실행되고,
자체 시작이 끝난 뒤 파일을 엽니다.

## Quick Look 미리보기 {#quick-look}

Mac에서는 Finder에서 데이터 파일을 선택하고 **스페이스**를 누르면 아무것도 열지 않고 그
열과 처음 몇 행을 볼 수 있습니다. 미리보기는 DuckLocal.app 안에 들어 있으며, 따로 설치할
것은 없습니다. 앱과 마찬가지로 macOS 12 이상이 필요합니다.

| 파일 | 미리보기가 보여 주는 내용 |
| --- | --- |
| `.parquet` | 열과 타입, 처음 50행, 그리고 파일 푸터에서 행 수, 행 그룹, 압축 방식, 작성한 프로그램 |
| `.duckdb`, `.ddb` | 테이블 수, 저장 형식(**DuckDB …에서 읽기 가능**), 가장 큰 테이블 다섯 개(각각 추정 행 수와 처음 50행 포함) |
| `.csv`, `.tsv` | 스니핑된 타입이 붙은 열과 처음 50행 — 원시 텍스트가 아닌 테이블로 |
| `.jsonl`, `.ndjson` | 열과 처음 50행 |

일반 `.json`과 Excel 파일은 macOS 자체 미리보기에 맡깁니다.

미리보기가 하는 일과 하지 않는 일:

- 절대 쓰지 않습니다. 데이터베이스는 읽기 전용으로 연결됩니다.
- 파일 전체를 스캔하지 않습니다: 행은 `LIMIT`이고, 행 수는 형식이 그것을 저장하는
  경우(Parquet의 푸터, 데이터베이스의 추정값)에만 표시됩니다.
- 아무것도 내려받지 않습니다: DuckDB 확장 기능은 설치도 로드도 되지 않습니다.
- 200자를 넘는 셀은 잘립니다. 페이지 텍스트는 영어입니다.
- 읽을 수 없는 파일에는 그 이유를 알려 주는 페이지가 표시됩니다.

스페이스를 눌러도 DuckLocal 미리보기가 나오지 않으면:

1. DuckLocal이 **응용 프로그램** 폴더에 있는지 확인하고 한 번 실행하세요. macOS는 앱을
   처음 볼 때 미리보기를 등록합니다.
2. 터미널에서 Quick Look을 재설정하세요: `qlmanage -r`. 그런 다음 다시 시도하세요.
3. 시스템 설정의 확장 기능 설정에서 Quick Look 아래 **DuckLocal Preview**가 켜져 있는지
   확인하세요.

## 이름 지정

파일의 뷰는 확장자를 뺀 파일 이름을 바탕으로 지어지며, 유효한 식별자가 되도록 정리됩니다.
그 이름이 연결에서 이미 쓰이고 있으면 DuckLocal이 카운터를 붙입니다:
`events`, 그다음 `events_2`, `events_3`. 따라서 서로 다른 디렉터리에 있는 같은 이름의 두
파일은 서로 다른 뷰를 갖게 됩니다.

중복 검사는 적힌 그대로의 경로 텍스트로 하므로 `./a.csv`와 `a.csv`는 서로 다른 두 파일로
취급됩니다.

## 제한

- **열기 요청당 데이터 파일 256개.** 이 상한은 폴더마다가 아니라 한 요청의 모든 경로를
  합친 것에 적용됩니다 — 실수로 홈 디렉터리를 드롭했을 때 연결이 몇 분씩 붙잡히지 않도록
  존재합니다. 상한에 닿으면 DuckLocal이 그렇게 알려 주고 처음 256개 파일을 연결합니다.
- 이전 세션에서 시작 시 다시 연결되는 파일은 이 상한의 적용을 받지 않습니다.

## 등록된 소스 관리

등록된 파일은 사이드바의 **로컬 파일** 그룹에 나타나며, 각각 뷰 이름, 파일 이름, 행 수가
붙습니다. 파일을 선택하면 그 파일에 대한 `SELECT` 문이 생성됩니다.

파일 행의 **×**는 확인 대화상자 뒤에 그 파일을 제거합니다. 제거는 뷰를 떨어뜨리고 등록을
잊는 것이며, **원본 파일은 그대로입니다.**

**스키마 새로 고침**은 카탈로그와 등록된 파일을 다시 불러옵니다.

## 기억되는 것

등록된 파일 목록 — 그 경로, 뷰 이름, 종류 — 은 DuckLocal 자체의 기록 데이터베이스에
저장되고 다음 실행 시 다시 연결되므로, 떠날 때의 워크스페이스가 그대로 돌아옵니다.
[연결된 데이터베이스](#kept-across-connections)도 마찬가지입니다. 기본 데이터베이스 파일은
기억되지 *않습니다*: 데이터베이스를 지정하지 않으면 실행할 때마다 메모리에서 시작합니다.

디스크상의 위치는 [설정과 앱 데이터](settings-and-data.md)를 참고하세요.
