基本用法：

  • jq '.' result.json：格式化输出整个 JSON。
  • 一般建议把过滤器放在单引号里，避免 shell 提前解释特殊字符。

基础查询

  • . —— 引用当前输入上下文（Identity）。
  • .foo —— 提取对象的指定属性。
  • .foo.bar —— 深度优先的链式属性访问。
  • .["foo.bar"] —— 访问包含非标准标识符（点号、空格或特殊符号）的键名。
  • .foo? —— 可选访问，当键不存在或类型不匹配时，静默忽略而非抛出运行时异常。

数组查询

  • .[0] / .[-1] —— 零值索引与逆向索引取值。
  • .[1:3] —— 切片，包含 1，不包含 3。
  • .[:3] —— 前 3 个元素。
  • .[-2:] —— 最后 2 个元素。
  • .[] —— 展开数组中的每个元素，以数据流形式输出。
  • .[]? —— 可选展开，不是数组/对象时不报错。

管道与结果收集

| 是标准 Unix 管道语义，将左侧表达式的求值结果流式传递给右侧作为输入。
.[] 把一个数组拆成数据流； [...] 把数据流整合成json数组。在进行长度计算（length）等操作前，必须确保流已完成聚合。
  • .items[] | .name —— 先展开 items，再取每项的 name。
  • .id, .name —— 对同一份输入跑多个查询，分别输出多个结果。
  • [.items[].name] —— 捕获迭代器输出的元素流，并重新封装为标准 JSON 数组。
  • {user, title} —— 只保留指定字段。
  • {id: .id, city: .address.city} —— 重组对象，同时改字段名。

条件筛选

  • .[] | select(.age >= 18) —— 过滤年龄大于等于 18 的元素。
  • .[] | select(.status == "ok") —— 过滤指定字段值。
  • .[] | select(.enabled == true and .role == "admin") —— 多条件组合。
  • .name // "unknown" —— 字段为 null、false 或不存在时给默认值。

常用查询函数

  • length —— 取长度，最常用于字符串、数组、对象。
  • keys —— 取对象所有 key；如果输入是数组，则返回索引数组。
  • has("id") —— 判断对象是否包含某个 key。
  • map(.name) —— 对数组中每个元素执行同一查询。
  • map(select(.enabled)) —— 对数组按条件筛选。
  • contains("prod") —— 判断是否包含子串 / 子数组 / 子对象。
  • test("^prod-") —— 用正则判断字符串是否匹配。

排序 / 去重 / 分组

  • sort —— 普通排序。
  • sort_by(.age) —— 按字段排序。
  • min_by(.score) —— 取字段最小项。
  • max_by(.score) —— 取字段最大项。
  • group_by(.status) —— 按字段分组。
  • unique_by(.id) —— 按字段去重。

常见组合