JSON 파일에서 결과까지
파일은 원래 자리에 그대로 있습니다. DuckDB가 쿼리할 때마다 제자리에서 읽습니다.
파일 놓기
events.ndjson은events라는 뷰가 되고,logs.json.gz는logs가 됩니다. 파일이 배열인지, 객체 하나인지, 한 줄에 객체 하나인지는 DuckDB가 판단합니다.구조 확인
스키마 사이드바는 중첩 객체를
STRUCT열로, 배열을LIST열로, 필드와 함께 보여 줍니다. 개요 탭은 결과의 각 열을 분석합니다.테이블처럼 쿼리
점 표기법으로 중첩 필드를 필터링하고,
unnest로 배열을 펼치고, 열어 둔 다른 파일과 결과를 조인하세요.
상용구 코드 없이 중첩 필드를
주문 항목 배열이 있는 주문은 주문마다 한 행, items 목록을 가진 행이 됩니다. unnest로 그 목록을 항목마다 한 행으로 바꾸면 각 항목의 필드는 점 하나로 꺼낼 수 있습니다.
레코드마다 구조가 다른 데이터에는 json_extract_string(col, '$.a.b[0].c')가 경로를 따라가 텍스트를 반환합니다. 값이 있든 없든 상관없습니다.
-- orders.ndjson: one order per line, -- each with an items array WITH lines AS ( SELECT order_id, unnest(items) AS item FROM orders ) SELECT item.sku, sum(item.qty) AS units FROM lines GROUP BY item.sku ORDER BY units DESC;
로그, 내보내기 파일, API 덤프
폴더나 logs/2026-*/*.json.gz 같은 패턴을 지정하면 일치하는 모든 파일이 데이터로 열립니다. 압축 파일은 풀 필요가 없습니다.
CloudTrail의 {"Records": [...]}처럼 레코드를 객체 하나로 감싸는 도구도 있습니다. ducklocal schema는 그런 구조를 알아채고, 힌트로 레코드를 행으로 읽는 SQL을 알려 줍니다.
- JSON 배열, 단일 객체, JSON Lines
- 압축 파일을 바로 읽기
- 폴더와 glob 패턴
- CSV, Parquet, Excel 데이터와 조인
- 결과를 CSV나 Parquet으로 내보내기
Finder의 NDJSON 뷰어
Mac에서 .jsonl이나 .ndjson 파일을 선택하고 스페이스 바를 누르세요. DuckLocal의 Quick Look 미리보기가 열과 처음 50행을 글자 더미가 아닌 표로 보여 줍니다. 미리보기는 쓰지 않고, 파일 전체를 읽지 않으며, 아무것도 다운로드하지 않습니다.
명령줄에서 JSON 다루기
같은 읽기 방식이 화면 없이도 동작합니다. ducklocal schema는 중첩된 열까지 포함해 JSON 파일의 열을 보여 주고, --stats는 이를 분석합니다. ducklocal query는 문장 하나를 실행하고 타입이 있는 JSON을 출력하므로, AI 에이전트가 필드 이름을 추측하지 않고 로그를 쿼리할 수 있습니다.
$ ducklocal schema events.jsonl $ ducklocal query --sql \ "SELECT json_extract_string(event, '$.payload.items[0].sku') AS sku, count(*) AS n FROM read_ndjson_objects('events.jsonl') GROUP BY 1 ORDER BY n DESC"
JSON과 SQL에 관한 질문
- DuckLocal은 어떤 JSON 형식을 열 수 있나요?
- JSON 문서(
.json), 줄 단위 JSON(.ndjson,.jsonl), 그리고logs.json.gz같은 압축 버전입니다. 각 파일은 파일 이름의 뷰가 됩니다. - 중첩 객체는 어떻게 처리되나요?
- DuckDB는 중첩 객체를
STRUCT열로, 배열을LIST열로 추론합니다. 점 표기법으로 접근하고,unnest로 목록을 펼치고, 구조가 불규칙한 데이터에는 경로를 지정한json_extract_string을 쓰세요. - CloudTrail 로그처럼 레코드가 배열로 감싸져 있으면요?
ducklocal schema는 파일이 레코드 목록을 감싼 객체 하나라는 것을 알아채고, 힌트로 레코드를 행으로 읽는 SQL을 알려 줍니다. 문서의 CloudTrail 예제에서 전체 과정을 볼 수 있습니다.- Mac용 NDJSON 뷰어가 있나요?
- 있습니다. DuckLocal을 설치한 뒤 Finder에서
.jsonl이나.ndjson파일을 선택하고 스페이스 바를 누르면, 앱을 열지 않아도 Quick Look이 열과 처음 50행을 보여 줍니다. - DuckLocal이 내 JSON 파일을 업로드하나요?
- 아니요. 파일은 앱 안의 DuckDB가 제자리에서 읽습니다. 서버로 복사되지 않으며 계정도 원격 측정도 없습니다.
관련 항목: SQL로 CSV 쿼리 · SQL로 Excel 쿼리 · Parquet 뷰어 · 로컬 데이터 분석
내 JSON에 SQL 실행하기
DuckLocal을 다운로드하고, JSON 파일이나 로그 폴더를 놓고, 첫 질문을 던져 보세요.