데이터 소스
DuckLocal은 파일을 인메모리 DuckDB 연결의 뷰로 만들고, 데이터베이스 파일을 열었다면 그 파일의 뷰로 만듭니다. 다른 데이터베이스를 그 옆에 둘 수도 있습니다. 설정할 것은 없습니다. 파일에서 SQL, 차트, 내보내기로 이어지는 간결한 경로는 로컬 데이터 분석 워크플로를 참고하세요.
데이터를 여는 방법
모두 같은 경로 해석 규칙을 거칩니다:
- 명령줄의 경로 —
ducklocal ./logs/ billing.parquet - 제목 표시줄의 열기 메뉴: 파일 열기, 폴더 열기, 또는 경로나 glob 입력. 마지막 항목은 입력한 경로나 네이티브 선택기에서 고른 경로를 위해 데이터 열기 대화상자를 엽니다
- 창 어디든 파일이나 폴더를 끌어다 놓기
- Mac에서는 Finder가 DuckLocal에 넘기는 파일 — Finder에서 열기 참고
열려 있는 데이터베이스를 바꾸지 않고 옆에 추가하려면 **열기 → 데이터베이스 연결…**을 사용하세요 — 연결된 데이터베이스를 참고하세요.
macOS에서는 Finder에서 Parquet과 DuckDB 파일을 더블클릭해 열거나, 스페이스 바를 눌러 DuckLocal을 실행하지 않고 Quick Look으로 Parquet, DuckDB, CSV, TSV, JSON Lines 파일의 처음 몇 행을 미리 볼 수 있습니다.
지원하는 파일 형식
확장자는 대소문자를 구분하지 않고 일치합니다.
| 확장자 | 읽는 방법 |
|---|---|
.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로 읽으세요.
그 밖의 것은 데이터 파일이 아닙니다 — 데이터베이스 파일을 참고하세요.
워크북은 뷰가 아니라 테이블이 되는 유일한 형식이며 모든 시트를 가져옵니다. 첫 시트는 확장자를 뺀 파일 이름을 이름으로 쓰고, 나머지는 {stem}_{sheet name}이라는 이름이 됩니다. 빈 시트는 건너뜁니다. 열 타입은 셀에서 추론합니다 — 정수는 BIGINT, 정수와 부동 소수점이 섞이면 DOUBLE, 날짜는 TIMESTAMP, 섞여 있거나 인식할 수 없는 값은 VARCHAR가 되고, 빈 셀은 NULL로 가져옵니다.
폴더와 패턴
디렉터리는 재귀적으로 순회하며, 안의 모든 데이터 파일이 뷰가 됩니다. 순회에는 두 가지 규칙이 적용됩니다:
- 숨김 항목(
.으로 시작하는 이름)은 건너뛰고, 그 하위 트리로 내려가지 않습니다. - 심볼릭 링크는 따라가지 않습니다. 트리 위쪽으로 이어지는 링크를 따라가면 끝나지 않으며, 링크된 디렉터리는 보통 실제로 있는 위치에서 순회됩니다.
파일은 정렬된 순서로 연결되므로 같은 폴더는 항상 같은 워크스페이스를 만듭니다.
패턴에는 *(임의 길이의 문자)와 ?(정확히 한 문자)를 쓸 수 있습니다. 일치는 경로 구성 요소마다 파일 시스템을 대상으로 이루어지므로, 패턴이 디렉터리를 가로지를 수 있습니다:
ducklocal './data/2026-0*/*.parquet'이스케이프 문자는 없습니다. **는 특별하지 않습니다 — 단일 *처럼 동작하며 재귀하지 않습니다. 디렉터리에 일치하는 패턴은 그 디렉터리를 건너뜁니다. 연결되는 것은 파일뿐입니다. 여기서도 숨김 항목은 건너뜁니다.
따옴표로 감싸지 않은 패턴은 DuckLocal이 보기 전에 셸이 확장합니다. 그래도 괜찮습니다. 패턴을 따옴표로 감쌀 때는 DuckLocal이 확장하기를 원할 때뿐입니다 — 예를 들어 셸이 일치하는 항목을 찾지 못해 오류를 낼 경우입니다.
한 번에 많은 CSV 파일
DuckLocal이 연결하는 각 파일은 자체적으로 스니핑한 스키마를 가진 별도 뷰가 되므로, 서로 맞지 않는 두 CSV가 서로를 깨뜨리지 않습니다. 함정은 하나의 SQL 읽기가 여러 파일에 걸칠 때 나타납니다:
SELECT * FROM read_csv('data/*.csv', union_by_name = true)타입 스니핑은 파일마다 다를 수 있습니다. 리더는 샘플에서 열의 타입을 추론합니다. 어디서나 숫자인 열이 한 파일에서
'NULL'문자열을 하나 포함하면 전체 읽기가 변환 오류로 실패하며,SELECT목록의 캐스트는 너무 늦습니다 — 읽기 자체가 오류를 냅니다. 대신 모든 열을 텍스트로 읽고 SQL에서 캐스트하세요:sqlSELECT 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).
데이터베이스 파일
DuckLocal은 한 번에 하나의 기본 데이터베이스를 가집니다: 인메모리이거나, 열어 둔 DuckDB 파일입니다. 데이터 파일은 기본 데이터베이스의 뷰가 됩니다. 다른 데이터베이스를 그 옆에 연결할 수도 있습니다.
존재하는 경로이면서 데이터 파일이 아닌 것은 뷰로 연결되지 않고 대신 기본 데이터베이스로 열립니다. 확장자는 중요하지 않습니다: .db, .duckdb, 심지어 .md 경로도 데이터베이스로 취급되며, 실제로 열 수 있는지는 DuckDB가 판단합니다.
몇 가지 짚어 둘 결과가 있습니다:
- 새 데이터베이스는 데이터 열기 대화상자에서만 만들어집니다. 아직 없는
.duckdb로 끝나는 경로를 입력하면 DuckLocal이 없는 상위 폴더와 함께 데이터베이스를 만듭니다. 그 밖의 곳 — 명령줄, 선택기, 드롭, Finder — 에서는 존재하지 않는 경로가File not found로 보고됩니다. - 데이터베이스를 열면 기본 데이터베이스가 바뀝니다. 등록한 파일과 연결한 데이터베이스는 새 연결에 다시 연결됩니다. S3 자격 증명은 그렇지 않으므로 S3을 다시 설정하세요.
- 파일을 열 수 없으면 DuckLocal이 이유를 알려 줍니다 (아래). 시작 시에는 시작에 실패하는 대신 인메모리 워크스페이스로 폴백합니다. 실행 중이라면 가지고 있던 워크스페이스가 그대로 유지됩니다.
- 이미 기본 데이터베이스 옆에 연결된 파일은 먼저 연결이 해제된 뒤 기본 데이터베이스로 열립니다. 그 열기가 실패하면 연결이 되돌아옵니다. 이미 기본 데이터베이스인 파일을 열면 그대로 재사용합니다.
데이터베이스 파일이 열려 있는 동안 데이터 파일을 연결하면 그 뷰가 해당 데이터베이스 파일에 기록됩니다 — 세션에만 있는 것이 아니라 그곳에 유지됩니다.
데이터베이스가 열리지 않을 때
DuckDB가 파일을 거부하면 DuckLocal이 파일의 처음 바이트를 직접 읽고, 그 바이트가 실패를 설명하는 경우 DuckDB 자체 메시지 위에 이유와 해결 방법을 표시합니다. 정확한 오류를 위해 DuckDB 메시지는 아래에 남습니다. 설명은 인터페이스 언어로 표시됩니다.
| 파일의 정체 | DuckLocal이 알려 주는 내용 |
|---|---|
| DuckLocal에 내장된 것보다 최신 DuckDB가 쓴 DuckDB 파일 | 두 버전, 그리고 최신 DuckDB에서 실행해 파일을 DuckLocal이 읽을 수 있는 형식으로 복사하는 SQL(아래) |
| v0.9 이하의 DuckDB 파일 | 그 파일을 쓴 DuckDB에서 EXPORT DATABASE 'dir'을 실행한 뒤 DuckLocal에서 IMPORT DATABASE 'dir' 실행 |
| SQLite 데이터베이스 | DuckDB 파일이 아닙니다. 대신 연결하세요 — 데이터베이스 연결… 또는 INSTALL sqlite; ATTACH '…' (TYPE sqlite); |
| DuckDB 파일이 아닌 다른 것 | 대신 CSV, Parquet, JSON, Excel 파일을 데이터 파일로 여세요 |
최신 DuckDB의 파일이라면 메시지에 파일 경로와 DuckLocal의 DuckDB 버전이 채워집니다. 파일을 만든 DuckDB에서 실행한 뒤 compat.duckdb를 여세요:
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 메시지만 표시합니다. 문제 해결을 참고하세요.
어떤 DuckDB가 데이터베이스를 읽을 수 있는가
데이터베이스 파일을 열면 상태 표시줄에 그 경로가 표시됩니다. 그 위에 마우스를 올리면 파일의 저장 형식(이를 읽을 수 있는 가장 오래된 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에서는 읽을 수 없습니다.
연결된 데이터베이스
기본 데이터베이스 옆에 다른 DuckDB 또는 SQLite 파일을 연결해 그것들을 함께 쿼리할 수 있습니다 — 예를 들어 오늘의 데이터 옆에 스냅숏을 두는 경우입니다.
- 제목 표시줄의 열기 메뉴를 열고 **데이터베이스 연결…**을 고릅니다.
- 경로를 입력하거나 찾아보기를 클릭해 파일을 고릅니다.
- 파일을 변경할 생각이 아니라면 읽기 전용을 체크한 채로 둡니다. 기본값으로 체크되어 있습니다.
- 연결을 클릭합니다.
데이터베이스는 파일 이름에서 별칭을 얻고, 그 테이블을 alias.table(또는 alias.schema.table)로 쿼리합니다:
-- 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 경로는 그때 새 빈 데이터베이스로 만들어집니다. 읽기 전용이면 대신 연결이 실패합니다.
- 같은 파일은 두 번 연결되지 않습니다. 이미 열려 있는 파일 — 기본 데이터베이스이든 연결된 것이든 — 을 연결하려 하면 *이 데이터베이스는 이미 열려 있습니다: …*라고 표시됩니다.
사이드바에서
모든 데이터베이스가 스키마 트리에 나타납니다. 기본 데이터베이스와 연결된 데이터베이스, 빈 데이터베이스까지 포함해서요. 데이터베이스는 해당되는 경우 이름 옆에 읽기 전용 또는 sqlite를 표시하고, 툴팁에 그 파일을 보여 줍니다.
데이터베이스를 마우스 오른쪽 버튼으로 클릭하면:
- 기본 데이터베이스로 사용 —
USE를 실행하므로 데이터베이스 이름이 없는 테이블 이름은 그곳에서 해석됩니다. 상태 표시줄에 현재 해석 위치가 표시됩니다. - 데이터베이스 연결 해제 — 연결을 해제하고 기억에서 지우므로 다음에 다시 나타나지 않습니다. 기본 데이터베이스였다면 세션이 먼저 기본 데이터베이스로 돌아갑니다. 파일 자체는 그대로입니다.
그 메뉴의 나머지는 스키마 브라우저와 기록에서 설명합니다.
연결을 넘어 유지됨
연결된 데이터베이스는 별칭과 읽기 전용 설정과 함께 DuckLocal 자체의 기록 데이터베이스에 저장되고, 새 연결마다 다시 연결됩니다: 다음 실행 시, 다른 데이터베이스를 연 뒤, 그리고 새 인메모리 데이터베이스 이후에요.
- 파일이 없는 데이터베이스는 조용히 건너뜁니다. 등록은 유지되므로 파일이 돌아오면 다시 나타납니다 — DuckLocal이 그 자리에 빈 데이터베이스를 만드는 일은 없습니다.
- 이미 열려 있는 데이터베이스는 기본 데이터베이스이든 아니든 두 번째로 연결되지 않습니다.
- 새 기본 데이터베이스에 그 별칭의 데이터베이스가 이미 있으면 DuckLocal은 *연결할 수 없습니다 …: 이름 …이(가) 열려 있는 데이터베이스에서 사용 중입니다.*라고 표시합니다.
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 파일은 대시보드 탭으로 열립니다. DuckLocal이 실행 중이 아니면 먼저 실행되고, 자체 시작이 끝난 뒤 파일을 엽니다.
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 미리보기가 나오지 않으면:
- DuckLocal이 응용 프로그램 폴더에 있는지 확인하고 한 번 실행하세요. macOS는 앱을 처음 볼 때 미리보기를 등록합니다.
- 터미널에서 Quick Look을 재설정하세요:
qlmanage -r. 그런 다음 다시 시도하세요. - 시스템 설정의 확장 기능 설정에서 Quick Look 아래 DuckLocal Preview가 켜져 있는지 확인하세요.
이름 지정
파일의 뷰는 확장자를 뺀 파일 이름을 바탕으로 지어지며, 유효한 식별자가 되도록 정리됩니다. 그 이름이 연결에서 이미 쓰이고 있으면 DuckLocal이 카운터를 붙입니다: events, 그다음 events_2, events_3. 따라서 서로 다른 디렉터리에 있는 같은 이름의 두 파일은 서로 다른 뷰를 갖게 됩니다.
중복 검사는 적힌 그대로의 경로 텍스트로 하므로 ./a.csv와 a.csv는 서로 다른 두 파일로 취급됩니다.
제한
- 열기 요청당 데이터 파일 256개. 이 상한은 폴더마다가 아니라 한 요청의 모든 경로를 합친 것에 적용됩니다 — 실수로 홈 디렉터리를 드롭했을 때 연결이 몇 분씩 붙잡히지 않도록 존재합니다. 상한에 닿으면 DuckLocal이 그렇게 알려 주고 처음 256개 파일을 연결합니다.
- 이전 세션에서 시작 시 다시 연결되는 파일은 이 상한의 적용을 받지 않습니다.
등록된 소스 관리
등록된 파일은 사이드바의 로컬 파일 그룹에 나타나며, 각각 뷰 이름, 파일 이름, 행 수가 붙습니다. 파일을 선택하면 그 파일에 대한 SELECT 문이 생성됩니다.
파일 행의 **×**는 확인 대화상자 뒤에 그 파일을 제거합니다. 제거는 뷰를 떨어뜨리고 등록을 잊는 것이며, 원본 파일은 그대로입니다.
스키마 새로 고침은 카탈로그와 등록된 파일을 다시 불러옵니다.
기억되는 것
등록된 파일 목록 — 그 경로, 뷰 이름, 종류 — 은 DuckLocal 자체의 기록 데이터베이스에 저장되고 다음 실행 시 다시 연결되므로, 떠날 때의 워크스페이스가 그대로 돌아옵니다. 연결된 데이터베이스도 마찬가지입니다. 기본 데이터베이스 파일은 기억되지 않습니다: 데이터베이스를 지정하지 않으면 실행할 때마다 메모리에서 시작합니다.
디스크상의 위치는 설정과 앱 데이터를 참고하세요.
