jq 入门：从格式化到复杂过滤

一、先准备一份示例数据

下面这份数据和站内工作台内置的「填入示例」一致，本文所有表达式都可以直接对 它 执行， 结果与文中一致：

{
  "store": {
    "book": [
      { "category": "reference", "title": "Sayings", "author": "Nigel Rees", "price": 8.95 },
      { "category": "fiction", "title": "Sword of Honour", "author": "Evelyn Waugh", "price": 12.99 },
      { "category": "fiction", "title": "Moby Dick", "author": "Herman Melville", "price": 8.99 }
    ],
    "bicycle": { "color": "red", "price": 19.95 }
  }
}

二、jq 的三条基本功

每条 jq 表达式描述的都是「对当前输入做什么」，把下面三种动作串起来，就能写出大部分查询：

• 取字段：.key。. 代表「当前输入」本身， .store 取 store 字段， 再 .book 继续下钻；字段名带特殊符号时用 .["weird-key"]。
• 展开数组：[]。.store.book 是整个数组（一个值）； .store.book[] 会把数组拆开，把三个元素依次输出（三个值）。
• 管道：|。 把左边的输出当作右边的输入：.store.book | length 即「先取 book，再求长度」。表达式从左到右读，就是数据的流动方向。

用方括号把一串管道包起来，可把「多行输出」重新收集成一个数组：[.store.book[] | .title] 得到 ["Sayings","Sword of Honour","Moby Dick"]，而不加方括号时是三个独立输出。

三、jq 的常用写法

下表覆盖入门最常用的一批写法，均可对示例数据直接运行：

更进阶的内建函数如 group_bysort_byaddtest// 见下文实战与速查表。

四、实战：对示例数据逐条运行

下表每一行都可以在上面的示例数据上复现（结果为实际输出值）：

五、常见错误与排查

• select 只过滤、不投影。select(.price < 10) 输出的是整个元素；只要标题需再接一段管道： select(.price < 10) | .title。
• 想要数组却忘了方括号。.store.book[] | .title 是三个独立输出（三行裸串）；套上外层方括号 [.store.book[] | .title] 才得到一个数组。
• 把 JSONPath 的 $ 或 @ 带进 jq。 jq 里的「当前输入」是 .， 不是 $ 或 @；过滤要写 select(.price < 10)， 容器与字段都点开头，例如 .store.book。
• 对字符串做算术。 对非数字值做 +- 或 tonumber 会触发运行时错误， 结果区会原样显示 jq 报错并归类为「jq 运行时错误」。
• 误以为 keys 保持原顺序。keys 返回的是排序后的键名（示例里是 ["bicycle","book"]）， 不是数据里的书写顺序；需要原顺序时可结合 to_entries。

排查建议：先用 . 看整体结构，再用 keys 或 .. 确认层级，然后逐步加管道。 对 null 取字段在 jq 1.8 中不报错（如 {} | .a.b 得 null）， 取不到数据时优先怀疑层级，而不是以为表达式崩了。

六、速查表

工作台内置的速查卡按「基础 / 遍历与映射 / 过滤与分组 / 对象与默认值」四组给出可运行示例，点击即填入表达式，可对照下表速记：