Skip to content

jq 常用配方 详解

日常使用的 jq 过滤器,按用途分组:取值、过滤与选择、操作集合、转换值与字符串、重塑为新对象或数组、就地更新路径、按逻辑分支,以及进阶的归约运算,还有决定输入输出形态的命令行标志。每一行将过滤器与其产生的结果配对。

jq 是一个过滤器:它从 stdin 读取 JSON,运行由管道符分隔的表达式组成的流水线,并把 JSON 写到 stdout。点号表示当前值,一切都建立在它之上。最快的入门方式是把真实数据管道给下面的配方并观察输出。按 jq 'filter' file.json 或 curl ... | jq 'filter' 的方式运行。

参考表格 · 65 条目
65 of 65 rows
访问
整个输入,美化格式后输出。
某个键上的值,或嵌套键上的值。
名称含特殊字符的键上的值。
数组的第一个元素(负数从末尾计数)。
数组的每个元素,或对象的每个值,各占一行。
键上的值,或 null;键缺失时不报错。
过滤与选择
条件为真时输入原样通过,否则什么都不输出。
对数组的每个元素应用表达式并收集结果。
对象排序后的键名,或所有值,以数组返回。
数组或字符串的长度,或对象中键的数量。
仅保留 age 大于 18 的元素,合成一个数组。
集合
至少一个元素、或每个元素为真或通过过滤器时返回真。
键 k 存在于对象中时为真;in 从键的一侧执行同样的测试。
第一个元素、最后一个元素,或 f 的前 n 个输出。
数组中最小或最大的值。
从 0 到 n 的数字,每个作为单独的输出。
嵌套数组折叠成一个扁平数组。
x 出现在输入中某处时为真;inside 调换角色。
自底向上对每个值应用 f,然后重建整个输入。
转换
只取每个元素 price 字段的数组。
数字数组的总和,或对象数组的合并结果。
把值强制转为字符串,或把数字字符串转为数字。
将输入编码为 JSON 字符串或 base64。
转换为小写的字符串。
字符串
把表达式的值拼接进文本的字符串。
把模式的每处匹配、或仅第一处,替换为 s。
按分隔符把字符串拆成数组,或把数组合成一个字符串。
用模式测试字符串,或提取匹配与命名捕获组。
仅在存在时去掉前缀或后缀。
真或假:字符串以 s 开头或结尾。
转换为大写的字符串。
把数组编码为一行 CSV、一行 TSV,或加引号的 shell 参数。
重塑
只含输入 id 和 name 字段的新对象。
由每个 item 的 name 组成的数组。
把对象变成由 {key, value} 对象组成的数组。
由 {key, value} 对象数组构建的对象。
元素按 cat 字段分组成子数组。
按字段排序,或每个不同 id 只保留一个元素。
更新与路径
对键上的值运行 f 来更新它。
用 v 覆盖键上的值。
就地给 count 处的值加上 n。
按数组形式的路径读取、写入或删除值。
控制与逻辑
c 为真时得到 a,否则 b;用 elif 增加分支。
运行 f;f 失败时改用错误消息运行 g。
携带 msg 报错停止,除非被 try 捕获。
完全没有输出;该分支从结果中直接消失。
组合真值与假值,或取反。
进阶
把整个数组折叠成一个累计总和。
类似 reduce,但每一步后都发出状态,而不只是最后一步。
下一个输入,或剩余的全部输入,在过滤器运行中途拉入。
值的 JSON 文本形式,或把 JSON 文本解析回值。
把 base64 文本解码回原始字符串。
结构深处的赋值,沿途创建缺失的层级。
a 不为 null 或 false 时取 a,否则取 b(默认值)。
移除了一个键之后的输入。
输入中的每条路径,以键数组形式从顶到底输出。
变量与 CLI
把 $name 定义为 shell 字符串,可在过滤器内使用。
从原始 JSON 定义 $name,适用于数字、布尔、数组或对象。
把 $name 定义为整个 JSON 文件的内容。
原样打印字符串结果,不带引号和转义。
每个结果紧凑打印成一行,无缩进。
在 null 上运行一次过滤器,从零构建输出。
过滤器运行前把全部输入读入一个数组。
根据最后一个输出设置退出码,便于 shell 脚本测试结果。
在过滤器内读取的环境变量的值。