---
title: "SQL로 JSON, NDJSON 파일 쿼리 | DuckLocal"
description: "JSON, NDJSON, JSON Lines 파일에 DuckDB SQL을 실행하세요. 압축 여부는 상관없습니다. 중첩 객체는 열이 되어 필터링, 펼치기, CSV와 Parquet과의 조인을 내 컴퓨터에서 할 수 있습니다."
image: https://ducklocal.app/og-image.jpg?v=2
language: ko
---

# SQL로 JSON 파일 쿼리

JSON, NDJSON, 압축된 로그 파일을 DuckLocal에 놓으면 테이블이 됩니다. 중첩 객체는 열이 되어 필터링하고, 펼치고, CSV와 Parquet과 조인할 수 있습니다. `jq` 파이프라인을 짤 필요도, 스크립트를 관리할 필요도 없습니다.

macOS, Windows, Linux용 무료 오픈 소스. 파일은 제자리에서 읽고 절대 업로드하지 않습니다.

- .json .ndjson .jsonl
- 압축된 .json.gz도 가능
- 중첩 필드를 열로
- JSON Lines용 Quick Look

## JSON 파일에서 결과까지

파일은 원래 자리에 그대로 있습니다. DuckDB가 쿼리할 때마다 제자리에서 읽습니다.

1. **파일 놓기.** `events.ndjson`은 `events`라는 뷰가 되고, `logs.json.gz`는 `logs`가 됩니다. 파일이 배열인지, 객체 하나인지, 한 줄에 객체 하나인지는 DuckDB가 판단합니다.
2. **구조 확인.** 스키마 사이드바는 중첩 객체를 `STRUCT` 열로, 배열을 `LIST` 열로, 필드와 함께 보여 줍니다. 개요 탭은 결과의 각 열을 분석합니다.
3. **테이블처럼 쿼리.** 점 표기법으로 중첩 필드를 필터링하고, `unnest`로 배열을 펼치고, 열어 둔 다른 파일과 결과를 조인하세요.

## 상용구 코드 없이 중첩 필드를

주문 항목 배열이 있는 주문은 주문마다 한 행, `items` 목록을 가진 행이 됩니다. `unnest`로 그 목록을 항목마다 한 행으로 바꾸면 각 항목의 필드는 점 하나로 꺼낼 수 있습니다.

레코드마다 구조가 다른 데이터에는 `json_extract_string(col, '$.a.b[0].c')`가 경로를 따라가 텍스트를 반환합니다. 값이 있든 없든 상관없습니다.

[JSONL과 중첩 JSON](https://ducklocal.app/docs/ko/cli#jsonl-and-nested-json) · [DuckDB JSON 레퍼런스](https://duckdb.org/docs/stable/data/json/overview)

```sql
-- 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을 알려 줍니다.

[폴더와 패턴](https://ducklocal.app/docs/ko/data-sources#folders-and-patterns) · [CloudTrail 로그를 로컬에서 감사하기](https://ducklocal.app/docs/ko/example-cloudtrail)

- JSON 배열, 단일 객체, JSON Lines
- 압축 파일을 바로 읽기
- 폴더와 glob 패턴
- CSV, Parquet, Excel 데이터와 조인
- 결과를 CSV나 Parquet으로 내보내기

## Finder의 NDJSON 뷰어

Mac에서 `.jsonl`이나 `.ndjson` 파일을 선택하고 스페이스 바를 누르세요. DuckLocal의 Quick Look 미리보기가 열과 처음 50행을 글자 더미가 아닌 표로 보여 줍니다. 미리보기는 쓰지 않고, 파일 전체를 읽지 않으며, 아무것도 다운로드하지 않습니다.

[Quick Look 미리보기](https://ducklocal.app/docs/ko/data-sources#quick-look)

> **Parquet으로 보관하고 싶나요?** 어떤 쿼리 결과든 Parquet으로 내보내세요. 파일은 더 작고, 열에는 타입이 있으며, 다음에 읽을 때 훨씬 빠릅니다. [Parquet 뷰어 보기 →](https://ducklocal.app/ko/use-cases/parquet-viewer/)

## 명령줄에서 JSON 다루기

같은 읽기 방식이 화면 없이도 동작합니다. `ducklocal schema`는 중첩된 열까지 포함해 JSON 파일의 열을 보여 주고, `--stats`는 이를 분석합니다. `ducklocal query`는 문장 하나를 실행하고 타입이 있는 JSON을 출력하므로, AI 에이전트가 필드 이름을 추측하지 않고 로그를 쿼리할 수 있습니다.

[CLI 가이드 읽기](https://ducklocal.app/docs/ko/cli) · [AI 에이전트를 위한 SQL](https://ducklocal.app/ko/use-cases/ai-agent-sql/)

```bash
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 쿼리](https://ducklocal.app/ko/use-cases/query-csv-with-sql/) · [SQL로 Excel 쿼리](https://ducklocal.app/ko/use-cases/query-excel-with-sql/) · [Parquet 뷰어](https://ducklocal.app/ko/use-cases/parquet-viewer/) · [로컬 데이터 분석](https://ducklocal.app/ko/use-cases/local-data-analysis/)

## 내 JSON에 SQL 실행하기

DuckLocal을 다운로드하고, JSON 파일이나 로그 폴더를 놓고, 첫 질문을 던져 보세요.

## 링크

- [DuckLocal 다운로드](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [CloudTrail 예제 따라 하기](https://ducklocal.app/docs/ko/example-cloudtrail)
- [설치하고 첫 쿼리 실행하기](https://ducklocal.app/docs/ko/getting-started)

Source: https://ducklocal.app/ko/use-cases/query-json-with-sql/
