从 JSON 文件到结果
文件留在原地。每次查询时,DuckDB 都在原处读取它。
拖入文件
events.ndjson会变成名为events的视图,logs.json.gz则是logs。DuckDB 会自己判断文件是数组、单个对象,还是每行一个对象。看清数据的结构
表结构侧栏会把嵌套对象显示为
STRUCT列、把数组显示为LIST列,并列出它们的字段。概览标签页会分析结果的每一列。像查询表一样查询它
用点号对嵌套字段过滤,用
unnest展开数组,再把结果和你打开的任何其他文件 JOIN。
嵌套字段,不写样板代码
一个带有订单明细数组的订单,会变成每个订单一行、带一个 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 转储
把 DuckLocal 指向一个文件夹,或 logs/2026-*/*.json.gz 这样的模式,所有匹配的文件都会作为数据打开。压缩文件无需解压。
有些工具会把记录包在一个对象里,比如 CloudTrail 的 {"Records": [...]}。ducklocal schema 能识别这种结构,它给出的提示里就有把记录读成行的 SQL。
- JSON 数组、单个对象和 JSON Lines
- 直接读取压缩文件
- 文件夹与通配模式
- 可与 CSV、Parquet 和 Excel 数据联合查询
- 结果导出为 CSV 或 Parquet
Finder 里的 NDJSON 查看器
在 Mac 上选中一个 .jsonl 或 .ndjson 文件,按下空格键。DuckLocal 的快速查看预览会以表格形式显示它的列和前 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文件并按空格键,快速查看就会显示它的列和前 50 行,无需打开应用。 - DuckLocal 会上传我的 JSON 文件吗?
- 不会。文件由应用内的 DuckDB 在原处读取,不会被复制到任何服务器,也没有账户和遥测。
相关页面:用 SQL 查询 CSV · 用 SQL 查询 Excel · Parquet 查看器 · 本地数据分析