---
title: "用 SQL 查询 JSON 和 NDJSON 文件 | DuckLocal"
description: "对 JSON、NDJSON 和 JSON Lines 文件运行 DuckDB SQL，压缩与否都可以。嵌套对象会变成列，可以过滤、展开，并与 CSV 和 Parquet 联合查询，全部在你自己的电脑上完成。"
image: https://ducklocal.app/og-image.jpg?v=2
language: zh-CN
---

# 用 SQL 查询 JSON 文件

把 JSON、NDJSON 或压缩的日志文件拖进 DuckLocal，它就变成一张表。嵌套对象会变成列，可以过滤、展开，并与 CSV 和 Parquet 联合查询。不用写 `jq` 管道，也不用维护脚本。

免费开源，支持 macOS、Windows 和 Linux。文件在原处读取，从不上传。

- .json .ndjson .jsonl
- 也支持压缩的 .json.gz
- 嵌套字段直接成为列
- JSON Lines 支持快速查看

## 从 JSON 文件到结果

文件留在原地。每次查询时，DuckDB 都在原处读取它。

1. **拖入文件。** `events.ndjson` 会变成名为 `events` 的视图，`logs.json.gz` 则是 `logs`。DuckDB 会自己判断文件是数组、单个对象，还是每行一个对象。
2. **看清数据的结构。** 表结构侧栏会把嵌套对象显示为 `STRUCT` 列、把数组显示为 `LIST` 列，并列出它们的字段。概览标签页会分析结果的每一列。
3. **像查询表一样查询它。** 用点号对嵌套字段过滤，用 `unnest` 展开数组，再把结果和你打开的任何其他文件 JOIN。

## 嵌套字段，不写样板代码

一个带有订单明细数组的订单，会变成每个订单一行、带一个 `items` 列表。`unnest` 把这个列表变成每个明细一行，每个明细的字段用一个点就能取到。

如果每条记录的结构都不一样，`json_extract_string(col, '$.a.b[0].c')` 会沿路径取值并返回文本，不管那里有没有值。

[JSONL 与嵌套 JSON](https://ducklocal.app/docs/zh/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 转储

把 DuckLocal 指向一个文件夹，或 `logs/2026-*/*.json.gz` 这样的模式，所有匹配的文件都会作为数据打开。压缩文件无需解压。

有些工具会把记录包在一个对象里，比如 CloudTrail 的 `{"Records": [...]}`。`ducklocal schema` 能识别这种结构，它给出的提示里就有把记录读成行的 SQL。

[文件夹与模式](https://ducklocal.app/docs/zh/data-sources#folders-and-patterns) · [在本地审计 CloudTrail 日志](https://ducklocal.app/docs/zh/example-cloudtrail)

- JSON 数组、单个对象和 JSON Lines
- 直接读取压缩文件
- 文件夹与通配模式
- 可与 CSV、Parquet 和 Excel 数据联合查询
- 结果导出为 CSV 或 Parquet

## Finder 里的 NDJSON 查看器

在 Mac 上选中一个 `.jsonl` 或 `.ndjson` 文件，按下空格键。DuckLocal 的快速查看预览会以表格形式显示它的列和前 50 行，而不是一大片文本。预览从不写入，从不扫描整个文件，也不下载任何东西。

[快速查看预览](https://ducklocal.app/docs/zh/data-sources#quick-look)

> **想存成 Parquet？** 把任何查询结果导出为 Parquet：文件更小，列有类型，下次读取也快得多。 [看看 Parquet 查看器 →](https://ducklocal.app/zh/use-cases/parquet-viewer/)

## 在命令行里处理 JSON

同样的读取方式在无界面模式下也能用。`ducklocal schema` 会显示 JSON 文件的列（包括嵌套的列），`--stats` 会分析它们。`ducklocal query` 运行一条语句并输出带类型的 JSON，AI 智能体查询日志时就不必去猜字段名。

[阅读 CLI 指南](https://ducklocal.app/docs/zh/cli) · [面向 AI 智能体的 SQL](https://ducklocal.app/zh/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` 文件并按空格键，快速查看就会显示它的列和前 50 行，无需打开应用。

**DuckLocal 会上传我的 JSON 文件吗？** 不会。文件由应用内的 DuckDB 在原处读取，不会被复制到任何服务器，也没有账户和遥测。

相关页面：[用 SQL 查询 CSV](https://ducklocal.app/zh/use-cases/query-csv-with-sql/) · [用 SQL 查询 Excel](https://ducklocal.app/zh/use-cases/query-excel-with-sql/) · [Parquet 查看器](https://ducklocal.app/zh/use-cases/parquet-viewer/) · [本地数据分析](https://ducklocal.app/zh/use-cases/local-data-analysis/)

## 对你自己的 JSON 运行 SQL

下载 DuckLocal，拖入一个 JSON 文件或一整个日志文件夹，问出你的第一个问题。

## 链接

- [下载 DuckLocal](https://github.com/JetSquirrel/DuckLocal/releases/latest)
- [跟着 CloudTrail 示例走一遍](https://ducklocal.app/docs/zh/example-cloudtrail)
- [安装并运行第一条查询](https://ducklocal.app/docs/zh/getting-started)

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