用 SQL 查询 JSON 文件

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

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

从 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 · DuckDB 的 JSON 参考

-- 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。

文件夹与模式 · 在本地审计 CloudTrail 日志

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

Finder 里的 NDJSON 查看器

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

快速查看预览

在命令行里处理 JSON

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

阅读 CLI 指南 · 面向 AI 智能体的 SQL

Terminal
$ 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 在原处读取,不会被复制到任何服务器,也没有账户和遥测。

对你自己的 JSON 运行 SQL

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