jq 1.7 手册

身份：.

最简单的过滤器是.。此过滤器接收其输入并产生相同的值作为输出。也就是说，这是身份运算符。

由于 jq 默认美化所有输出，一个只包含.的简单程序可以用来格式化来自curl.

的 JSON 输出。尽管身份过滤器从未修改其输入的值，但 jq 处理有时会使其看起来好像它确实进行了修改。例如，使用当前 jq 的实现，我们会看到表达式：

1E1234567890 | .

将字符串除以另一个字符串会使用第二个字符串作为分隔符分割第一个字符串。1.7976931348623157e+308。这是因为，在解析数字的过程中，这个特定版本的 jq 将其转换为 IEEE754 双精度表示，从而丢失了精度。

jq 处理数字的方式随着时间的推移而改变，并且根据相关 JSON 标准的参数，可能会进一步改变。因此，以下注释是理解它们旨在描述当前 jq 版本的当前版本，并且不应将其解释为规定：

(1) 对尚未转换为 IEEE754 双精度表示的数字的任何算术运算都会触发转换为 IEEE754 表示。

(2) jq 将尝试保持数字字面量的原始十进制精度，但在表达式1E1234567890中，如果指数太大，精度将丢失。

(3) 在 jq 程序中，一个负号将触发数字转换为 IEEE754 表示。

(4) 如果可用，比较将使用未截断的 big decimal 表示的数字进行，如以下示例之一所示。

对象标识符-索引：.foo, .foo.bar

最简单的有用过滤器产生消息的形式.foo形式。当给定一个 JSON 对象（又名字典或哈希）作为输入时，.foo如果键存在，则产生键 "foo" 的值，否则产生 null。

A filter of the form .foo.bar等同于.foo | .bar.

元数据中的.foo语法只适用于简单的、类似标识符的键，也就是说，键全部由字母数字字符和下划线组成，并且不以数字开头。

如果键包含特殊字符或以数字开头，你需要用双引号将其包围，像这样：."foo$"，或者.["foo$"].

For example.["foo::bar"]和.["foo.bar"]可以工作，而.foo::bar不行。

可选对象标识符-索引：.foo?

类似.foo，但如果.不是对象，则不会输出错误。

对象索引：.[<string>]

你也可以使用类似于.["foo"] (.foo上的语法来查找对象的字段，但只有对于类似标识符的字符串才是简写版本）。

数组索引：.[<number>]

当索引值是整数时，.[<number>]可以索引数组。数组是零基的，所以.[2]返回第三个元素。

允许负索引，-1 指向最后一个元素，-2 指向倒数第二个元素，以此类推。

数组/字符串切片：.[<number>:<number>]

元数据中的.[<number>:<number>]语法返回数组的子数组或字符串的子字符串。由.[10:15]返回的数组长度为 5，包含从索引 10（包含）到索引 15（排除）的元素。两个索引都可以是负数（在这种情况下，它从数组的末尾向后计数），或者省略（在这种情况下，它指的是数组的开始或结束）。

数组/对象值迭代器：.[]

如果你使用.[index]语法，但完全省略了索引，它将返回数组的所有元素。使用 of the elements of an array. Running .[]输入[1,2,3]将产生数字作为三个单独的结果，而不是一个数组。形式为.foo[]等同于.foo | .[].

你也可以在对象上使用它，它将返回对象的所有值。

注意，迭代运算符是值的生成器。

.[]?

. Like.[]，但如果 . 不是数组或对象，则不会输出错误。形式为.foo[]?等同于.foo | .[]?.

逗号：,

如果两个过滤器由逗号分隔，则相同的输入将被提供给两者，并且两个过滤器的输出值流将按顺序连接：首先，所有由左表达式产生的输出，然后是所有由右表达式产生的输出。例如，过滤器.foo, .bar，产生 "foo" 字段和 "bar 字"段作为单独的输出。

元数据中的, operator is one way to construct generators.

管道：|

运算符通过将左侧过滤器的输出(s)输入到右侧过滤器的输入中来组合两个过滤器。它类似于 Unix shell 的管道，如果你习惯使用的话。

如果左侧过滤器产生多个结果，右侧过滤器将对每个结果运行。所以，表达式.[] | .foo从输入数组的每个元素检索 "foo" 字段。这是一个笛卡尔积，可能会令人惊讶。

注意，a87502 内部定义为递归的 jq 函数。在.a.b.c is the same as .a | .b | .c.

注意，e08c57: 不会设置.是管道中特定阶段的输入值，具体是：出现.表达式的位置。因此.a | . | .b is the same as .a.b相同，因为.在中间指的是.a产生的值。

括号

括号就像在任何典型的编程语言中一样作为分组运算符工作。

数组构造：[]

与 JSON 类似，[]用于构造数组，如[1,2,3]。数组的元素可以是任何 jq 表达式，包括管道。所有表达式产生的所有结果都被收集到一个大数组中。你可以使用它来根据已知数量的值构造数组（如[.foo, .bar, .baz]）或收集过滤器的所有结果到一个数组（如[.items[].name])

。一旦你理解了 "," 运算符，你就可以从不同的角度来看待 jq 的数组语法：表达式[1,2,3]不是使用逗号分隔数组的内建语法，而是应用[]运算符（收集结果）到表达式 1,2,3 （它会产生三个不同的结果）。

如果你有一个过滤器X产生四个结果，那么表达式[X]将产生一个结果，一个包含四个元素的数组。

对象构造：{}

与 JSON 类似，{}用于构造对象（又名字典或哈希），如：{"a": 42, "b": 17}.

如果键是 "标识符类似" 的，那么可以省略引号，像{a:42, b:17}。变量引用作为键表达式使用变量的值作为键。除了常量字面量、标识符或变量引用的键表达式外，需要将它们括起来，例如，{("a"+"b"):59}.

The value 可以是任何表达式（尽管你可能需要用括号将其括起来，例如，如果它包含冒号），它将应用于 {} 表达式的输入（记住，所有过滤器都有一个输入和输出）。

{foo: .bar}

将产生 JSON 对象{"foo": 42}如果给定 JSON 对象{"bar":42, "baz":43}作为输入。你可以使用它来选择对象的部分字段：如果输入是一个具有 "user"、"title"、"id" 和 "content" 字段的对象，并且你只需要 "user" 和 "title"，你可以写

{user: .user, title: .title}

因为这非常常见，所以有一个快捷语法：{user, title}.

如果表达式之一产生多个结果，将产生多个字典。如果输入的

{"user":"stedolan","titles":["JQ Primer", "More JQ"]}

，则表达式

{user, title: .titles[]}

将产生两个输出：

{"user":"stedolan", "title": "JQ Primer"}
{"user":"stedolan", "title": "More JQ"}

将键括起来意味着它将作为表达式进行评估。使用相同的输入，表达式

{(.user): .titles}

将字符串除以另一个字符串会使用第二个字符串作为分隔符分割第一个字符串。

{"stedolan": ["JQ Primer", "More JQ"]}

变量引用作为键使用变量的值作为键。如果没有值，则变量的名称成为键，其值成为值，

"f o o" as $foo | "b a r" as $bar | {$foo, $bar:$foo}

将字符串除以另一个字符串会使用第二个字符串作为分隔符分割第一个字符串。

{"foo":"f o o","b a r":"f o o"}

递归下降：..

递归下降.，产生每个值。这是与零参数recurse内建函数相同。这是为了类似于 XPath//运算符。注意..a不工作；使用.. | .a代替。在下面的示例中，我们使用.. | .a?查找所有对象键的值..

这在与path(EXP)（也见下文）和?操作符一起使用时特别有用。

加法：+

操作符+接受两个过滤器，将它们都应用于相同的输入，并将结果相加在一起。"加" 的含义取决于所涉及的类型：

• 数字通过普通算术加法。

• 数组通过连接成一个更大的数组来加法。

• 字符串通过连接成一个更大的字符串来加法。

• 对象通过合并来加法，即插入两个对象的所有键值对到一个单一的组合对象中。如果两个对象都包含相同键的值，则右侧的对象会获胜。（对于递归合并使用+ wins. (For recursive merge use the *操作符。）

null可以加到任何值，并返回其他值不变。

减法：-

除了数字的正常算术减法之外，还可以使用-操作符在数组上移除第一数组中所有第二数组元素的实例。

乘法、除法、模运算：*, /, %

当给定两个数字时，这些中缀操作符按预期工作。除以零会引发错误。x % y计算x模y。

将字符串乘以数字会产生该字符串重复指定次数的连接。"x" * 0将字符串除以另一个字符串会使用第二个字符串作为分隔符分割第一个字符串。"".

Dividing a string by another splits the first using the second as separators.

两个对象相乘会递归合并：这像加法一样工作，但如果两个对象都包含相同键的值，并且这些值是对象，则使用相同的策略合并它们。

abs

内置函数abs被天真地定义为：if . < 0 then - . else . end.

对于数值输入，这是绝对值。有关此定义对数值输入的影响，请参阅身份过滤器部分。

要将一个数字的绝对值计算为浮点数，您可能希望使用fabs.

length

内置函数length获取各种不同类型值的长度：

• 数字的长度是它包含的 Unicode 代码点的数量（如果它是纯 ASCII，则等于其 JSON 编码的字节长度）。 is the number of Unicode codepoints it contains (which will be the same as its JSON-encoded length in bytes if it's pure ASCII).

• 数字的长度是其绝对值。 is its absolute value.

• 对象array，则输出

• 对象的长度是键值对的数量。 is the number of key-value pairs.

• nullnull is zero.

• 在length上使用布尔值是错误的。.

utf8bytelength

内置函数utf8bytelength输出用于在 UTF-8 中编码字符串的字节数。

keys, keys_unsorted

内置函数keys，当给定一个对象时，它返回其键数组。

键按“字母顺序”排序，按 Unicode 代码点顺序排序。这不是任何特定语言中有特别意义的顺序，但您可以确信对于具有相同键集的任何两个对象，它都是相同的，而不管区域设置设置如何。

When keys给定一个数组时，它返回该数组的有效索引：从 0 到 length-1 的整数。

元数据中的keys_unsorted与keys类似，但如果输入是对象，则键不会排序，相反，键将大致按插入顺序排列。

has(key)

内置函数has返回输入对象是否具有给定键，或者输入数组是否在给定索引处有元素。

has($key)与检查$key是否是keys返回的数组中的成员具有相同的效果，尽管has会更快。

in

内置函数in返回输入键是否在给定对象中，或者输入索引对应于给定数组中的元素。本质上，这是has.

map(f), map_values(f)

对于任何过滤器f, map(f)和map_values(f)将f应用于输入数组或对象中的每个值，即.[].

的值，在错误不存在的情况下，map(f)总是输出一个数组，而map_values(f)如果给定的是数组，则输出数组；如果给定的是对象，则输出对象。

当map_values(f)的输入是对象时，输出对象具有与输入对象相同的键，除了那些键的值在管道传递到f时产生没有任何值的键。

betweenmap(f)和map_values(f)的主要区别在于($x|f)的所有值形成数组，对于输入数组或对象中的每个值$x，而map_values(f)仅使用first($x|f).

Specifically, for object inputs,map_values(f)通过依次检查输入对象的每个键first(.[$k]|f)的值来构建输出对象。$k如果此表达式不产生任何值，则相应的键将被删除；否则，输出对象将在键处具有该值，$k.

这里有一些示例来阐明map和map_values应用于数组时的行为。这些示例假设输入在所有情况下都是[1]:

map(.+1)          #=>  [2]
map(., .)         #=>  [1,1]
map(empty)        #=>  []

map_values(.+1)   #=>  [2]
map_values(., .)  #=>  [1]
map_values(empty) #=>  []

map(f)等同于[.[] | f]和map_values(f)等同于.[] |= f.

实际上，这是它们的实现。

pick(pathexps)

输出输入对象或数组定义的投影，该投影由指定路径表达式序列定义，使得如果p是这些规范中的任何一个，则(. | p)将评估为与(. | pick(pathexps) | p)相同的值。对于数组，不应使用负索引和.[m:n]规范。

path(path_expression)

输出给定路径表达式.中的数组表示形式。输出是字符串数组（对象键）和/或数字数组（数组索引）。

路径表达式是像.a这样的 jq 表达式，但也是.[]。有两种类型的路径表达式：可以完全匹配的和不能完全匹配的。例如，.a.b.c是完全匹配的路径表达式，而.a[].b不是。

path(exact_path_expression)即使路径表达式在.中不存在，也会产生路径表达式的数组表示，如果. is null或数组或对象。

path(pattern)将产生与pattern匹配的路径的数组表示，如果路径在..

中存在。注意，路径表达式与普通表达式没有区别。表达式path(..|select(type=="boolean"))输出.中所有到布尔值的路径，并且只有这些路径。

del(path_expression)

内置函数del从对象中删除一个键及其对应的值。

getpath(PATHS)

内置函数getpath输出在.中每个路径处的值。ff7c0f: 示例PATHS.

setpath(PATHS; VALUE)

内置函数setpath将PATHS中的.到VALUE.

delpaths(PATHS)

内置函数delpaths删除PATHS中的.. PATHS必须是路径数组，其中每个路径都是字符串和数字的数组。

to_entries, from_entries, with_entries(f)

这些函数在对象和键值对数组之间进行转换。如果to_entries接受一个对象，则对于输入中的每个k: v条目，输出数组包括{"key": k, "value": v}.

from_entries，对于with_entries(f)的每个值，输出数组包括to_entries | map(f) | from_entries，对于from_entries accepts "key", "Key", "name", "Name", "value"，和"Value"的每个键。ff7c0f: 示例

select(boolean_expression)

函数select(f)如果f对于该输入返回 true，则输出其输入不变，否则不输出任何内容。

它在过滤列表时很有用：[1,2,3] | map(select(. >= 2))将为您提供[2,3].

arrays, objects, iterables, booleans, numbers, normals, finites, strings, nulls, values, scalars

这些内置函数仅选择输入为数组、对象、可迭代（数组或对象）、布尔值、数字、普通数字、有限数字、字符串、null、非 null 值和非可迭代值。

empty

empty返回没有结果。完全没有任何。甚至null.

它在某个时候很有用。如果您需要它，您就会知道。

error, error(message)

使用输入值或作为参数给出的消息产生错误。错误可以用 try/catch 捕获；见下文。

halt

停止 jq 程序而不产生进一步输出。jq 将以退出状态0.

halt_error, halt_error(exit_code)

停止 jq 程序而不产生进一步输出。输入将作为原始输出打印在stderr上（即字符串将没有双引号），没有任何装饰，甚至没有换行符。

给定的exit_code（默认为5）将是 jq 的退出状态。

例如，"Error: something went wrong\n"|halt_error(1).

$__loc__

产生一个具有 "file" 键和 "line" 键的对象，其值是$__loc__发生时的文件名和行号。

paths, paths(node_filter)

paths输出其输入中所有元素的路径（除了它不输出表示

paths(f)输出任何值f is true是paths(type == "number")将输出所有数值的路径。

add

过滤器add接受一个数组作为输入，并产生作为输出数组中元素的数组。这可能意味着求和、连接或合并，具体取决于输入数组元素的类型——这些规则与+操作符（如上所述）的规则相同。

，则输出add返回null.

any, any(condition), any(generator; condition)

过滤器any接受一个嵌套数组数组作为输入，并产生一个扁平数组，其中原始数组中的所有嵌套数组都被递归地替换为它们的值。您可以传递一个参数来指定要扁平化的嵌套级别数。true作为输出。如果输入是空数组，true.

，则输出any返回false.

元数据中的any(condition)形式应用于输入数组中的元素应用给定的条件。函数

元数据中的any(generator; condition)形式应用于给定生成器的所有输出应用给定的条件。

all, all(condition), all(generator; condition)

过滤器all接受一个嵌套数组数组作为输入，并产生一个扁平数组，其中原始数组中的所有嵌套数组都被递归地替换为它们的值。您可以传递一个参数来指定要扁平化的嵌套级别数。true作为输出。如果输入是空数组，true.

元数据中的all(condition)形式应用于输入数组中的元素应用给定的条件。函数

元数据中的all(generator; condition)形式应用于给定生成器的所有输出应用给定的条件。

，则输出all返回true.

flatten, flatten(depth)

过滤器flatten接受一个嵌套数组数组作为输入，并产生一个扁平数组，其中原始数组中的所有嵌套数组都被递归地替换为它们的值。您可以传递一个参数来指定要扁平化的嵌套级别数。

flatten(2)类似于flatten类似，但只扁平化到两个级别深。

range(upto), range(from; upto), range(from; upto; by)

元数据中的range生成一系列数字。range(4; 10)生成 6 个数字，从 4（包含）到 10（不包含）。数字作为单独的输出生成。使用[range(4; 10)]获取一个范围作为数组。

单参数形式生成从 0 到给定数字的数字，增量值为 1。

双参数形式生成从from到upto的数字，增量值为 1。

三参数形式生成from到upto的数字，增量值为by.

floor

元数据中的floor返回其数值输入的向下取整值。

sqrt

元数据中的sqrt function returns the square root of its numeric input.

tonumber

元数据中的tonumber function parses its input as a number. It will convert correctly-formatted strings to their numeric equivalent, leave numbers alone, and give an error on all other input.

tostring

元数据中的tostring function prints its input as a string. Strings are left unchanged, and all other values are JSON-encoded.

type

元数据中的type返回其参数的类型作为字符串，它是 null、boolean、number、string、array 或 object 中的一个。

infinite, nan, isinfinite, isnan, isfinite, isnormal

某些算术运算可能会产生无穷大和“不是数字”（NaN）值。内置函数isinfinite如果其输入是 NaN，则返回true。内置函数isnan如果其输入是 NaN，则返回true。内置函数infinite返回一个正无穷大值。内置函数nan返回一个 NaN。isnormal内置函数返回 true 如果其输入是正常数字。

注意，除以零会引发错误。

目前大多数在无穷大、NaN 和次正规数上执行的算术运算都不会引发错误。

sort, sort_by(path_expression)

元数据中的sort对其输入进行排序，输入必须是数组。值按以下顺序排序：

• null
• false
• true
• 数字
• 字符串，按字母顺序（按 unicode 代码点值）排序
• 数组，按词法顺序排序
• 对象

对象的排序顺序有点复杂：首先，它们通过比较它们的键集（按排序顺序的数组）进行比较，如果它们的键相等，则按键逐个比较值。

sort_by可以用来按对象的特定字段排序，或应用任何 jq 过滤器。sort_by(f)通过比较f的结果来比较两个元素。当f产生多个值时，它首先比较第一个值，如果第一个值相等，则比较第二个值，以此类推。

group_by(path_expression)

group_by(.foo)接受一个数组作为输入，将具有相同.foo字段的元素分组到单独的数组中，并将所有这些数组作为更大的数组元素输出，按.foo字段的值排序。可以替换

任何 jq 表达式，而不仅仅是字段访问，可以替换.foo的任何 jq 表达式，而不仅仅是字段访问。排序顺序与上面描述的sort函数相同。

min, max, min_by(path_exp), max_by(path_exp)

Find the minimum or maximum element of the input array.

元数据中的min_by(path_exp)和max_by(path_exp)允许您指定要检查的特定字段或属性，例如min_by(.foo)查找具有最小foo字段的值排序。可以替换

unique, unique_by(path_exp)

元数据中的unique接受一个数组作为输入，并产生一个去重的数组，其中包含与每个值对应的相同元素。函数

元数据中的unique_by(path_exp)将仅保留每个值获得的唯一值。将其视为从每个group.

reverse

函数

contains(element)

过滤器contains(b)如果 b 完全包含在输入中，则输出 true。字符串 B 包含字符串 A 如果 B 是 A 的子字符串。数组 B 包含数组 A 如果 B 中的所有元素都包含 A 中的任何元素。对象 B 包含对象 A 如果 B 中的所有值都包含 A 中具有相同键的值。所有其他类型如果它们相等，则假定它们包含彼此。ff7c0f: 示例

indices(s)

函数.其中s occurs. The input may be an array, in which case if s是数组，则输出索引将是.中所有元素都匹配s.

index(s), rindex(s)

函数index本身）。rindex) occurrence of s in the input.

inside

过滤器inside(b)如果输入完全包含在 b 中，则将产生 true。它本质上是一个反转版本。contains.

startswith(str)

输出true如果 . 以给定的字符串参数开头。

endswith(str)

输出true如果 . 以给定的字符串参数结尾。

combinations, combinations(n)

输出输入数组的元素的所有组合。如果给定参数n，它将输出输入数组的所有组合n重复。

ltrimstr(str)

输出其输入，如果它以给定的前缀字符串开头，则删除该前缀字符串。

rtrimstr(str)

输出其输入，如果它以给定的后缀字符串结尾，则删除该后缀字符串。

explode

将输入字符串转换为字符串的码点数字数组。

implode

explode 的逆。

split(str)

将输入字符串按分隔符参数拆分。

split当使用两个参数调用时，也可以根据正则表达式匹配进行拆分（见下文的正则表达式部分）。

join(str)

使用给定的参数作为分隔符连接输入的元素数组。它是split的逆。对任何输入字符串运行split("foo") | join("foo")都会返回该输入字符串。

输入中的数字和布尔值将转换为字符串。空值被视为空字符串。输入中的数组和对象不受支持。

ascii_downcase, ascii_upcase

输出一个输入字符串的副本，将其字母字符（a-z 和 A-Z）转换为指定的案例。

while(cond; update)

元数据中的while(cond; update) function allows you to repeatedly apply an update to .直到cond为假。

注意，a87502 内部定义为递归的 jq 函数。在while(cond; update) is internally defined as a recursive jq function. Recursive calls within while内部的递归调用不会消耗额外的内存，如果update对每个输入最多产生一个输出。请参阅高级主题部分。

repeat(exp)

元数据中的repeat(exp) function allows you to repeatedly apply expression exp到.直到引发错误。

注意，a87502 内部定义为递归的 jq 函数。在repeat(exp) is internally defined as a recursive jq function. Recursive calls within repeat内部的递归调用不会消耗额外的内存，如果exp对每个输入最多产生一个输出。请参阅高级主题部分。

until(cond; next)

元数据中的until(cond; next) function allows you to repeatedly apply the expression next，最初应用于.，然后应用于它自己的输出，直到cond为真。例如，这可以用来实现一个阶乘函数（见下文）。

注意，a87502 内部定义为递归的 jq 函数。在until(cond; next) is internally defined as a recursive jq function. Recursive calls within until()内部的递归调用不会消耗额外的内存，如果next对每个输入最多产生一个输出。请参阅高级主题部分。

recurse(f), recurse, recurse(f; condition)

元数据中的recurse(f) function allows you to search through a recursive structure, and extract interesting data from all levels. Suppose your input represents a filesystem:

{"name": "/", "children": [
  {"name": "/bin", "children": [
    {"name": "/bin/ls", "children": []},
    {"name": "/bin/sh", "children": []}]},
  {"name": "/home", "children": [
    {"name": "/home/stephen", "children": [
      {"name": "/home/stephen/jq", "children": []}]}]}]}

现在假设您想提取所有出现的文件名。您需要检索.name, .children[].name, .children[].children[].name，等等。您可以用以下方式完成此操作：

recurse(.children[]) | .name

当不使用参数调用时，recurse等同于recurse(.[]?).

recurse(f)等同于recurse(f; true)，并且可以在不考虑递归深度的情况下使用。

recurse(f; condition)是一个生成器，它首先发出 .，然后依次发出 .|f、.|f|f、.|f|f|f，等等，只要计算值满足条件。例如，要生成所有整数，至少原则上，可以写recurse(.+1; true).

在recurse中的递归调用不会消耗额外的内存，只要f对每个输入最多产生一个输出。请参阅高级主题部分。

walk(f)

元数据中的walk(f)递归地应用于输入实体的每个组件。当遇到数组时，首先将 f 应用于其元素，然后将其应用于数组本身；当遇到对象时，首先将 f 应用于所有值，然后将其应用于对象。在实践中，f 通常会测试其输入的类型，如下面的示例所示。第一个示例突出了在处理数组的数组元素之前处理数组本身的实用性。第二个示例显示了如何考虑更改输入中所有对象的键。

$JQ_BUILD_CONFIGURATION

这个内置绑定显示了 jq 可执行文件的构建配置。其值没有特定的格式，但可以预期它至少是./configure命令行参数，并且将来可能会丰富，以包括用于构建工具的版本字符串。

注意，这可以在命令行中使用--arg和相关选项覆盖。

$ENV, env

$ENV是一个表示环境变量的对象，这些变量是在 jq 程序启动时设置的。

env输出一个表示 jq 当前环境的对象。

目前还没有内置函数来设置环境变量。

transpose

转置一个可能参差不齐的矩阵（一个数组的数组）。

bsearch(x)

bsearch(x)在输入数组中搜索 x。如果输入已排序且包含 x，则bsearch(x)将返回其在数组中的索引；否则，如果数组已排序，它将返回 (-1 - ix) ，其中 ix 是插入点，这样在 ix 处插入 x 后，数组仍然保持排序。如果数组未排序，0d40c4: 将返回一个整数，该整数可能没有兴趣。bsearch(x) will return an integer that is probably of no interest.

字符串插值：\(exp)

在字符串中，您可以在反斜杠后用括号括起来的表达式中放入一个表达式。表达式返回的内容将被插值到字符串中。

转换为/从 JSON

元数据中的tojson和fromjson分别将值作为 JSON 文本导出或解析 JSON 文本为值。函数tojson与tostring不同，因为tostring返回未修改的字符串，而tojson将字符串编码为 JSON 字符串。

格式化字符串和转义

元数据中的@foo语法用于格式化和转义字符串，这对于构建 URL、语言（如 HTML 或 XML）中的文档等等非常有用。@foo可以单独作为过滤器使用，可能的转义是：

• @text:

调用tostring，参见该函数的详细信息。

• @json:

将输入序列化为 JSON。

• @html:

应用 HTML/XML 转义，通过将字符<>&'"映射到它们的实体等效物<, >, &, ', ".

• @uri:

应用百分比编码，通过将所有保留的 URI%XX序列。

• @csv:

输入必须是数组，它使用双引号对字符串进行分隔，并且通过重复来转义引号。

• @tsv:

输入必须是数组，它被渲染为 CSV0x09). Input characters line-feed (ascii 0x0a), carriage-return (ascii 0x0d), tab (ascii 0x09) and backslash (ascii 0x5c) will be output as escape sequences \n, \r, \t, \\ respectively.

• @sh:

The input is escaped suitable for use in a command-line for a POSIX shell. If the input is an array, the output will be a series of space-separated strings.

• @base64:

输入是适合在 POSIX shell 的命令行中使用的转义。如果输入是数组，输出将是空格分隔的字符串序列。

• @base64d:

将输入转换为 base64，如 RFC 4648 所指定。@base64的逆，输入按 RFC 4648 解码。注意：如果解码的字符串不是 UTF-16，则结果未定义。

这种语法可以与字符串插值以有用的方式组合。您可以跟随@foo标记和一个字符串字面量。字符串字面量的内容not be escaped. However, all interpolations made inside that string literal will be escaped. For instance,

@uri "https://www.google.com/search?q=\(.search)"

将为输入{"search":"what is jq?"}:

"https://www.google.com/search?q=what%20is%20jq%3F"

产生以下输出：

日期

jq 提供了一些基本日期处理功能，一些高级和低级内置函数。在所有情况下，这些内置函数都专门处理 UTC 中的时间。

元数据中的fromdateiso8601将 ISO 8601 格式的 datetime 解析为自 Unix 纪元（1970-01-01T00:00:00Z）以来的秒数。函数todateiso8601执行相反的操作。

元数据中的fromdate解析 datetime 字符串。目前fromdate仅支持 ISO 8601 datetime 字符串，但在将来它将尝试解析更多格式的 datetime 字符串。

元数据中的todate是todateiso8601.

元数据中的now输出当前时间，以自 Unix 纪元以来的秒数。

低级 jq 接口也提供了到 C 库时间函数的接口：strptime, strftime, strflocaltime, mktime, gmtime，和localtime。参考您的主操作系统文档中strptime和strftime使用的格式字符串。注意：这些不一定是 jq 中稳定的接口，特别是它们的本地化功能。

元数据中的gmtime消耗自 Unix 纪元以来的秒数，并输出格林尼治标准时间（GMT）的“分解时间”表示，作为一个表示数字的数组：年份、月份（零基），月份中的天（一基），一天中的小时，一小时内的小时，一分钟内的小时，一分钟内的秒数，一周中的天，一年中的天——所有这些都以一基为基准，除非另有说明。周数可能对于某些系统在 1900 年 3 月 1 日之前的日期或 2099 年 12 月 31 日之后的日期是错误的。

元数据中的localtime与gmtime函数类似，但使用本地时区设置。

元数据中的mktime消耗由gmtime和strptime.

元数据中的strptime(fmt)解析匹配fmt参数的输入字符串。输出是mktime和gmtime.

元数据中的strftime(fmt)使用给定的格式格式化时间（GMT）。strflocaltime类似，但使用本地时区设置。

be5d5d: 和strptime和strftime的格式字符串在典型的 C 库文档中描述。ISO 8601 datetime 的格式字符串是"%Y-%m-%dT%H:%M:%SZ".

jq 可能不支持某些系统上的一些或全部这些日期功能。特别是，%u和%j对于strptime(fmt)的规范在 macOS 上不受支持。

SQL-Style Operators

jq 提供了一些 SQL 风格的运算符。

• INDEX(stream; index_expression):

这个内置函数产生一个对象，其键由应用于每个值的给定索引表达式计算。

• JOIN($idx; stream; idx_expr; join_expr):

这个内置函数将给定流中的值连接到给定的索引。索引的键由应用于给定流中每个值的给定索引表达式计算。一个值在流中和来自索引的相应值组成的数组被传递到给定的连接表达式以生成每个结果。

• JOIN($idx; stream; idx_expr):

与JOIN($idx; stream; idx_expr; .).

• JOIN($idx; idx_expr):

相同。.to the given index, applying.to compute the index key. The join operation is as described above.

• IN(s):

This builtin outputstrue相同，如果.出现在给定的流中，否则它输出false.

• IN(source; s):

This builtin outputstrue如果源流中的任何值出现在第二个流中，否则它输出false.

builtins

返回一个列表，其中包含所有内置函数的名称，格式为name/arity。由于具有相同名称但不同参数个数的函数被视为不同的函数，all/0, all/1，和all/2都会出现在列表中。

==, !=

表达式 'a == b' 如果评估 a 和 b 的结果相等（即，如果它们表示等效的 JSON 值）则将产生 'true' ，否则产生 'false' 。特别是，字符串永远不会被视为等于数字。在检查 JSON 对象的相等性时，键的顺序无关紧要。如果你来自 JavaScript，请注意 jq 的==类似于 JavaScript 的===，即“严格相等”运算符。

!= 是“不等于”，'a != b' 返回与 'a == b' 相反的值

if-then-else-end

if A then B else C end将与B相同，如果A产生除 false 或 null 之外的值，但与C相同，否则。c343c6: 与

if A then B end is the same as if A then B else . end相同。即，如果没有else分支，则与.相同。这也适用于elif，如果没有else分支。检查 false 或 null 是比 JavaScript 或 Python 中发现的“真值”更简单的概念，但这意味着您有时必须更明确地说明您想要的条件。您不能用

Checking for false or null is a simpler notion of "truthiness" than is found in JavaScript or Python, but it means that you'll sometimes have to be more explicit about the condition you want. You can't test whether, e.g. a string is empty using if .name then A else B end测试字符串是否为空；您需要像if .name == "" then A else B end代替。

If the condition A产生多个结果，则B将针对每个不是 false 或 null 的结果评估一次，并且C将针对每个 false 或 null 评估一次。您可以使用

More cases can be added to an if using elif A then B语法将更多情况添加到 if 中。

>, >=, <=, <

比较运算符>, >=, <=, <返回其左参数是否大于、大于或等于、小于或等于其右参数（分别）。相应的顺序与

The ordering is the same as that described for sort中描述的相同。

and, or, not

jq 支持正常的布尔运算符and, or, not。它们具有与 if 表达式相同的真值标准 -false和null被认为是“假值”，而

如果运算符的某个操作数产生多个结果，运算符本身将产生一个结果对于每个输入。f4f43d: 实际上是一个内置函数，而不是运算符，所以它可以作为过滤器调用，而不是像

not is in fact a builtin function rather than an operator, so it is called as a filter to which things can be piped rather than with special syntax, as in .foo and .bar | not.

这样使用特殊语法。这些三个只产生true和false的值，所以只适用于真正的布尔运算，而不是常见的 Perl/Python/Ruby idiom of//运算符下面。

替代运算符：//

元数据中的//产生其左边的所有值，这些值既不是false也不是null，或者，如果左边的值除了false或null，然后//产生其右边的所有值。一个形式为

A filter of the form a // b的过滤器产生a的所有结果，这些结果既不是false或null。如果a产生没有结果，或者没有结果，或者没有结果，则false或null，然后a // b产生b.

的结果。这可用于提供默认值：.foo // 1将评估为1如果输入中没有.foo元素。它类似于如何在 Python 中使用or有时，'or' 形式的“或”与or operator is reserved for strictly Boolean operations).

Note: some_generator // defaults_here is not the same as some_generator | . // defaults_here不同。后者将为所有非false，非null值提供默认值，而前者不会。优先级规则可能会使这令人困惑。例如，在false, 1 // 2中，运算符// is 1，而不是false, 1--false, 1 // 2解析方式与false, (1 // 2)相同。在(false, null, 1) | . // 42中，运算符// is .，它始终只产生一个值，而在(false, null, 1) // 42中，运算符的左边是一个生成器，它生成三个值，并且由于它产生一个false和null，所以不会产生默认值。42 is not produced.

try-catch

通过使用try EXP catch EXP来捕获错误。第一个表达式被执行，如果它失败，则第二个表达式被执行，并带有错误消息。处理程序的输出，如果有的话，则作为如果它已经被输出的表达式输出。

元数据中的try EXP使用empty作为异常处理程序。

从控制结构中跳出

try/catch 的一个方便用法是跳出像reduce, foreach, while这样的控制结构，等等。

例如：

# Repeat an expression until it raises "break" as an
# error, then stop repeating without re-raising the error.
# But if the error caught is not "break" then re-raise it.
try repeat(exp) catch if .=="break" then empty else error

jq 有一个命名词法标签的语法，用于“跳出”或“回到”（如果适用）：

label $out | ... break $out ...

元数据中的break $label_name将导致程序表现得好像最左边的 (到左边)label $label_name生成的标签empty.

一样。标签之间的关系是词法的：标签必须从 break 可见。break and corresponding label is lexical: the label has to be "visible" from the break.

要跳出reduce，例如：

label $out | reduce .[] as $item (null; if .==false then break $out else ... end)

以下 jq 程序会产生语法错误：

break $out

因为没有可见的标签$out。

错误抑制/可选运算符：?

元数据中的?作为EXP?使用，是try EXP.

test(val), test(regex; flags)

. Likematch, but does not return match objects, onlytrue或falsefor whether or not the regex matches the input.

match(val), match(regex; flags)

match输出每个匹配项的对象。匹配项具有以下字段：

• offset- UTF-8 代码点从输入开始的位置偏移量
• length- UTF-8 代码点的匹配长度
• string- 匹配的字符串
• captures- 表示捕获组的对象数组。

捕获组对象具有以下字段：

• offset- UTF-8 代码点从输入开始的位置偏移量
• length- UTF-8 代码点的捕获组长度
• string- 捕获的字符串
• name- 捕获组的名称（或null如果它是未命名的）

未匹配任何内容的捕获组返回偏移量为 -1

capture(val), capture(regex; flags)

将命名的捕获组收集到一个 JSON 对象中，每个捕获组的名称作为键，匹配的字符串作为相应的值。

scan(regex), scan(regex; flags)

发出一个输入的非重叠子字符串流，这些子字符串与根据任何指定的标志匹配的 regex 匹配。如果没有匹配，则流为空。为了捕获每个输入字符串的所有匹配项，使用 idiom[ expr ]，例如[ scan(regex) ]. 如果 regex 包含捕获组，则过滤器发出一个包含捕获字符串的数组流。

split(regex; flags)

将输入字符串在每个 regex 匹配处分割。

为了向后兼容性，当使用单个参数调用时，5cfe4c: 在字符串上分割，而不是在 regex 上。split splits on a string, not a regex.

splits(regex), splits(regex; flags)

这些提供与它们的split对应项相同的结果，但作为流而不是数组。

sub(regex; tostring), sub(regex; tostring; flags)

发出通过在输入字符串中替换 regex 的第一个匹配项来获得的字符串tostring，之后进行插值。tostring应该是一个 jq 字符串或这样的字符串流，每个字符串都可以包含对命名捕获组的引用。命名捕获组实际上被作为 JSON 对象（如capture构建的）呈现给tostring，因此对捕获的变量名为 "x" 的引用将采用以下形式："\(.x)".

gsub(regex; tostring), gsub(regex; tostring; flags)

gsub类似于sub，但所有非重叠的 regex 出现都被替换为tostring，之后进行插值。如果第二个参数是 jq 字符串流，那么gsub将产生相应的 JSON 字符串流。

变量/符号绑定运算符：... as $identifier | ...

在 jq 中，所有过滤器都有一个输入和一个输出，因此无需手动连接来传递一个值从程序的这一部分到下一部分。许多表达式，例如a + b，将它们的输入传递给两个不同的子表达式（在这里a和b都传递了相同的输入），因此通常不需要变量来两次使用一个值。

例如，计算数组中数字的平均值需要大多数语言中的几个变量 - 至少一个来保存数组，也许一个用于每个元素或用于循环计数器。在 jq 中，它很简单add / length- 表达式是给数组并产生它的和，表达式是给数组并产生它的长度。add expression is given the array and produces its sum, and the length expression is given the array and produces its length.

因此，通常比定义变量更干净的方式来在 jq 中解决大多数问题。尽管有时它们确实使事情变得更容易，所以 jq 允许你使用expression as $variable定义变量。所有变量名都以$开头。这是一个稍微丑陋的数组平均示例：

length as $array_length | add / $array_length

我们需要更复杂的问题才能找到一个使用变量实际上使我们的生活更容易的情况。

假设我们有一个博客文章的数组，其中包含“author”和“title”字段，以及另一个映射作者用户名到真实姓名的对象。我们的输入看起来像：

{"posts": [{"title": "First post", "author": "anon"},
           {"title": "A well-written article", "author": "person1"}],
 "realnames": {"anon": "Anonymous Coward",
               "person1": "Person McPherson"}}

我们想要生成包含真实姓名的作者字段的帖子，如下所示：

{"title": "First post", "author": "Anonymous Coward"}
{"title": "A well-written article", "author": "Person McPherson"}

我们使用一个变量，$names，来存储真实姓名对象，这样我们就可以在查找作者用户名时稍后引用它：

.realnames as $names | .posts[] | {title, author: $names[.author]}

表达式exp as $x | ...的意思是：对于表达式exp的每个值，运行其余的管道，使用整个原始输入，并将$x设置为该值。因此as充当某种形式的

正如{foo}也是编写{foo: .foo}的方便方式一样，所以{$foo}也是编写{foo: $foo}.

的方便方式。as表达式通过提供匹配输入结构的模式来声明多个变量（这被称为“解构”）：

. as {realnames: $names, posts: [$first, $second]} | ...

数组模式中的变量声明（例如，. as [$first, $second]）绑定到数组的元素，从索引零开始，按顺序。当数组模式元素的索引处没有值时，null被绑定到该变量。

变量在其定义的其余表达式中作用域内，所以

.realnames as $names | (.posts[] | {title, author: $names[.author]})

将起作用，但

(.realnames as $names | .posts[]) | {title, author: $names[.author]}

不会。

对于编程语言理论家来说，更准确的说法是 jq 变量是词法作用域绑定。特别是没有办法改变绑定值；只能设置具有相同名称的新绑定，但这个新绑定在原来的位置是不可见的。

解构替代运算符：?//

解构替代运算符提供了一种简洁的机制来解构可以采取几种形式的输入。

假设我们有一个返回与它们关联的资源列表和事件的 API，我们想要为每个资源获取第一个事件的 user_id 和 timestamp。API（已经从 XML 拼凑起来）只有在资源有多个事件时才会将事件包装在数组中：

{"resources": [{"id": 1, "kind": "widget", "events": {"action": "create", "user_id": 1, "ts": 13}},
               {"id": 2, "kind": "widget", "events": [{"action": "create", "user_id": 1, "ts": 14}, {"action": "destroy", "user_id": 1, "ts": 15}]}]}

我们可以使用解构替代运算符来简单地处理这种结构变化：

.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$user_id, $ts}]} | {$user_id, $kind, $id, $ts}

或者，如果我们不确定输入是值的数组还是对象：

.[] as [$id, $kind, $user_id, $ts] ?// {$id, $kind, $user_id, $ts} | ...

每个替代不必定义所有相同的变量，但所有命名的变量都将可用于后续表达式。在替代中未匹配的变量将被null:

.resources[] as {$id, $kind, events: {$user_id, $ts}} ?// {$id, $kind, events: [{$first_user_id, $first_ts}]} | {$user_id, $first_user_id, $kind, $id, $ts, $first_ts}

此外，如果后续表达式返回错误，则替代运算符将尝试尝试下一个绑定。在最后替代期间发生的错误将传递通过。

[[3]] | .[] as [$a] ?// [$b] | if $a != null then error("err: \($a)") else {$a,$b} end

递归

You can give a filter a name using "def" syntax:

def increment: . + 1;

From then on, increment is usable as a filter just like a builtin function (in fact, this is how many of the builtins are defined). A function may take arguments:

def map(f): [.[] | f];

Arguments are passed as filters (functions with no arguments), not as values. The same argument may be referenced multiple times with different inputs (here f is run for each element of the input array). Arguments to a function work more like callbacks than like value arguments. This is important to understand. Consider:

def foo(f): f|f;
5|foo(.*2)

The result will be 20 because f is .*2, and during the first invocation of f . will be 5, and the second time it will be 10 (5 * 2), so the result will be 20. Function arguments are filters, and filters expect an input when invoked.

If you want the value-argument behaviour for defining simple functions, you can just use a variable:

def addvalue(f): f as $f | map(. + $f);

Or use the short-hand:

def addvalue($f): ...;

With either definition, addvalue(.foo) will add the current input's .foo field to each element of the array. Do note that calling addvalue(.[]) will cause the map(. + $f) part to be evaluated once per value in the value of . at the call site.

Multiple definitions using the same function name are allowed. Each re-definition replaces the previous one for the same number of function arguments, but only for references from functions (or main program) subsequent to the re-definition. See also the section below on scoping.

Scoping

There are two types of symbols in jq: value bindings (a.k.a., "variables"), and functions. Both are scoped lexically, with expressions being able to refer only to symbols that have been defined "to the left" of them. The only exception to this rule is that functions can refer to themselves so as to be able to create recursive functions.

For example, in the following expression there is a binding which is visible "to the right" of it, ... | .*3 as $times_three | [. + $times_three] | ..., but not "to the left". Consider this expression now, ... | (.*3 as $times_three | [. + $times_three]) | ...: here the binding $times_three is not visible past the closing parenthesis.

isempty(exp)

Returns true if exp produces no outputs, false otherwise.

limit(n; exp)

元数据中的limit function extracts up to n outputs from exp.

first(expr), last(expr), nth(n; expr)

元数据中的first(expr)和last(expr) functions extract the first and last values from expr, respectively.

元数据中的nth(n; expr) function extracts the nth value output by expr. Note that nth(n; expr) doesn't support negative values of n.

first, last, nth(n)

元数据中的first和last functions extract the first and last values from any array at ..

元数据中的nth(n) function extracts the nth value of any array at ..

reduce

元数据中的reduce syntax allows you to combine all of the results of an expression by accumulating them into a single answer. The form is reduce EXP as $var (INIT; UPDATE). As an example, we'll pass [1,2,3] to this expression:

reduce .[] as $item (0; . + $item)

For each result that .[] produces, . + $item is run to accumulate a running total, starting from 0 as the input value. In this example, .[] produces the results 1, 2，和3, so the effect is similar to running something like this:

0 | 1 as $item | . + $item |
    2 as $item | . + $item |
    3 as $item | . + $item

foreach

元数据中的foreach syntax is similar to reduce, but intended to allow the construction of limit and reducers that produce intermediate results.

The form is foreach EXP as $var (INIT; UPDATE; EXTRACT). As an example, we'll pass [1,2,3] to this expression:

foreach .[] as $item (0; . + $item; [$item, . * 2])

Like the reduce syntax, . + $item is run for each result that .[] produces, but [$item, . * 2] is run for each intermediate values. In this example, since the intermediate values are 1, 3，和6, the foreach expression produces [1,2], [2,6]，和[3,12]. So the effect is similar to running something like this:

0 | 1 as $item | . + $item | [$item, . * 2],
    2 as $item | . + $item | [$item, . * 2],
    3 as $item | . + $item | [$item, . * 2]

When EXTRACT is omitted, the identity filter is used. That is, it outputs the intermediate values as they are.

Recursion

如上所述，recurse使用递归，任何 jq 函数都可以是递归的。内置的while也是用递归实现的。

当递归调用左侧的表达式输出其最后一个值时，会优化尾调用。在实践中，这意味着递归调用左侧的表达式不应为每个输入产生超过一个输出。

例如：

def recurse(f): def r: ., (f | select(. != null) | r); r;

def while(cond; update):
  def _while:
    if cond then ., (update | _while) else empty end;
  _while;

def repeat(exp):
  def _repeat:
    exp, _repeat;
  _repeat;

生成器和迭代器

一些 jq 运算符和函数实际上是生成器，因为它们可以为每个输入产生零个、一个或多个值，就像在其他有生成器的编程语言中可以预期的那样。例如，.[]生成其输入中的所有值（输入必须是数组或对象），range(0; 10)生成 0 到 10 之间的整数，等等。

即使逗号运算符也是一个生成器，它首先生成逗号左侧表达式生成的值，然后生成逗号右侧表达式生成的值。

元数据中的empty生成器产生零个输出。内置的empty生成器回溯到前面的生成器表达式。

所有 jq 函数都可以通过使用内置生成器来成为生成器。使用递归和逗号运算符也可以构造新的生成器。如果递归调用位于“尾位置”，则生成器将是高效的。在下面的示例中，_range对自身的递归调用位于尾位置。示例展示了三个高级主题：尾递归、生成器构造和子函数。

input

输出一个新输入。

注意，当使用input时，通常需要使用命令行选项-n调用 jq，否则第一个实体将被丢失。

echo 1 2 3 4 | jq '[., input]' # [1,2] [3,4]

inputs

输出所有剩余输入，一次一个。

这主要用于对程序的输入进行归约。注意，当使用inputs时，通常需要使用命令行选项-n调用 jq，否则第一个实体将被丢失。

echo 1 2 3 | jq -n 'reduce inputs as $i (0; . + $i)' # 6

debug, debug(msgs)

这两个过滤器类似于.，但副作用是生成一个或多个消息到 stderr。

由debug过滤器产生消息的形式

["DEBUG:",<input-value>]

其中<input-value>是输入值的紧凑表示。这种格式将来可能会改变。

元数据中的debug(msgs)过滤器定义为(msgs | debug | empty), .，从而允许消息内容的高度灵活性，同时允许创建多行调试语句。

例如，表达式：

1 as $x | 2 | debug("Entering function foo with $x == \($x)", .) | (.+1)

会产生值 3，但以下两行将被写入 stderr：

["DEBUG:","Entering function foo with $x == 1"]
["DEBUG:",2]

stderr

打印其输入以原始和紧凑模式到 stderr，没有任何额外的装饰，甚至没有换行符。

input_filename

返回当前正在过滤的输入的文件名。注意，除非 jq 在 UTF-8 地区运行，否则这不会很好地工作。

input_line_number

返回当前正在过滤的输入的行号。

truncate_stream(stream_expression)

消耗一个数字作为输入，并从给定流式表达式的输出的左侧截断相应数量的路径元素。

fromstream(stream_expression)

输出与流表达式输出的值对应的值。

tostream

元数据中的tostream输出其输入的流式形式。

更新赋值：|=

这是“更新”运算符|=。它接受右侧的过滤器，并通过运行旧值通过这个表达式来计算被赋值给.的属性的新值。例如，(.foo, .bar) |= .+1将构建一个foo字段设置为输入的foo加1，以及bar字段设置为输入的bar加1的对象。

左侧可以是任何一般的路径表达式；参见path().

注意，b64df5: 的左侧引用的是|= refers to a value in .中的值。因此$var.foo |= . + 1不会按预期工作（$var.foo在.中不是一个有效或有用的路径表达式）；使用$var | .foo |= . + 1代替。

如果右侧输出没有值（即，empty），那么左侧路径将被删除，就像del(path).

如果右侧输出多个值，则只使用第一个（兼容性说明：在jq 1.5及更早版本中，它曾经是使用最后一个）。

算术更新赋值：+=, -=, *=, /=, %=, //=

jq有几个形式的运算符a op= b，它们都等效于a |= . op b。所以，+= 1可以用来增加值，与|= . + 1.

简单赋值：=

这是简单的赋值运算符。与其他运算符不同，右侧（RHS）的输入与左侧（LHS）的输入相同，而不是LHS路径处的值，并且RHS输出的所有值都将被使用（如下所示）。

如果=的右侧产生多个值，那么对于每个这样的值，jq将把左侧的路径设置为该值，然后它会输出修改后的.。例如，(.a,.b) = range(2)输出{"a":0,"b":0}，然后{"a":1,"b":1}。更新赋值形式（见上文）不这样做。

这个示例应该显示=和|=:

之间的区别。向{"a": {"b": 10}, "b": 20}前者将输入的

.a = .b

和

.a |= .b

提供输入a字段设置为b字段，并产生输出{"a": 20, "b": 20}。后者将输入的a字段设置为a字段的b字段，产生{"a": 10, "b": 20}.

复杂赋值

jq赋值左侧允许比大多数语言更多的事情。我们已经看到了左侧的简单字段访问，并且数组访问也同样有效：

.posts[0].title = "JQ Manual"

可能令人惊讶的是，左侧的表达式可能产生多个结果，引用输入文档中的不同位置：

.posts[].comments |= . + ["this is great"]

该示例将字符串"this is great"附加到输入中每个帖子的"comments"数组（其中输入是一个具有"posts"字段的字段，该字段是一个帖子数组）。

当jq遇到像'a = b'这样的赋值时，它在执行a时记录选择输入文档部分所采取的"路径"。然后，这个路径用于在执行赋值时找到要更改的输入部分。任何过滤器都可以用于等于运算符的左侧；无论它从输入中选择哪些路径，都会在那里执行赋值。

这是一个非常强大的操作。假设我们想要向博客帖子添加评论，使用上面相同的"blog"输入。这次，我们只想评论"stedolan"写的帖子。我们可以使用前面描述的"select"函数来找到这些帖子：

.posts[] | select(.author == "stedolan")

该操作提供的路径指向"stedolan"写的每个帖子，我们可以像之前一样对它们进行评论：

(.posts[] | select(.author == "stedolan") | .comments) |=
    . + ["terrible."]

import RelativePathString as NAME [<metadata>];

从搜索路径中的目录相对于给定路径导入模块。将.jq suffix will be added to the relative path string. The module's symbols are prefixed with NAME::.

可选的元数据必须是一个常量jq表达式。它应该是一个具有homepage and so on. At this time jq only uses the search key/value of the metadata. The metadata is also made available to users via the modulemeta builtin.

元数据中的search key in the metadata, if present, should have a string or array value (array of strings); this is the search path to be prefixed to the top-level search path.

include RelativePathString [<metadata>];

从搜索路径中的目录相对于给定路径导入模块，就像它被直接包含一样。将.jq suffix will be added to the relative path string. The module's symbols are imported into the caller's namespace as if the module's content had been included directly.

可选的元数据必须是一个常量jq表达式。它应该是一个具有homepage and so on. At this time jq only uses the search key/value of the metadata. The metadata is also made available to users via the modulemeta builtin.

import RelativePathString as $NAME [<metadata>];

从搜索路径中的目录相对于给定路径导入JSON文件。将.json suffix will be added to the relative path string. The file's data will be available as $NAME::NAME.

可选的元数据必须是一个常量jq表达式。它应该是一个具有homepage and so on. At this time jq only uses the search key/value of the metadata. The metadata is also made available to users via the modulemeta builtin.

元数据中的search key in the metadata, if present, should have a string or array value (array of strings); this is the search path to be prefixed to the top-level search path.

module <metadata>;

此指令完全是可选的。它不是正常运行所必需的。它只用于提供可以通过modulemeta builtin.

元数据必须是一个常量jq表达式。它应该是一个具有homepage. At this time jq doesn't use this metadata, but it is made available to users via the modulemeta builtin.

modulemeta

接收模块名称作为输入，并输出模块的元数据作为对象，模块的导入（包括元数据）作为deps key and the module's defined functions as an array value for the defs key.

程序可以使用此功能查询模块的元数据，然后可以使用这些元数据来搜索、下载和安装缺失的依赖项。