콘텐츠로 이동

데이터 소스 ​

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

데이터를 여는 방법 ​

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

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

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

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

지원하는 파일 형식 ​

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

확장자읽는 방법
.csv, .tsv, .txtread_csv_auto 뷰
.parquetread_parquet 뷰
.json, .ndjson, .jsonlread_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로 가져옵니다.

폴더와 패턴 ​

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

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

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

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

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

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

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

한 번에 많은 CSV 파일 ​

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).

데이터베이스 파일 ​

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를 여세요:

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 메시지만 표시합니다. 문제 해결을 참고하세요.

어떤 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 파일을 연결해 그것들을 함께 쿼리할 수 있습니다 — 예를 들어 오늘의 데이터 옆에 스냅숏을 두는 경우입니다.

  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 경로는 그때 새 빈 데이터베이스로 만들어집니다. 읽기 전용이면 대신 연결이 실패합니다.
  • 같은 파일은 두 번 연결되지 않습니다. 이미 열려 있는 파일 — 기본 데이터베이스이든 연결된 것이든 — 을 연결하려 하면 *이 데이터베이스는 이미 열려 있습니다: …*라고 표시됩니다.

사이드바에서 ​

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

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

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

그 메뉴의 나머지는 스키마 브라우저와 기록에서 설명합니다.

연결을 넘어 유지됨 ​

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

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

Finder에서 열기 ​

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

파일더블클릭연결 프로그램, 또는 Dock 아이콘에 드롭
.parquetDuckLocal에서 열림예
.duckdb, .ddbDuckLocal에서 열림예
.dashDuckLocal에서 열림예
.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 미리보기가 나오지 않으면:

  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 자체의 기록 데이터베이스에 저장되고 다음 실행 시 다시 연결되므로, 떠날 때의 워크스페이스가 그대로 돌아옵니다. 연결된 데이터베이스도 마찬가지입니다. 기본 데이터베이스 파일은 기억되지 않습니다: 데이터베이스를 지정하지 않으면 실행할 때마다 메모리에서 시작합니다.

디스크상의 위치는 설정과 앱 데이터를 참고하세요.

Apache-2.0 라이선스로 공개되었습니다.