jq语言

jq
	jq官方图标
编程范型	纯函数式，面向JSON，隐式，管道
設計者	Stephen Dolan
发行时间	2012年8月21日，12年前
当前版本	1.7.1（2023年12月13日；穩定版本）;
型態系統	动态
作用域	词法
實作語言	jq：C，gojq：Go，jaq：Rust，jqjq：jq
系统平台	跨平台
操作系统	跨平台
許可證	MIT
網站	jqlang.github.io/jq
受影响于
	Haskell，Icon，JSON，Unix shell，sed

jq是领域特定高级的纯函数式编程语言，它采用词法作用域，其中所有JSON值都是常量。jq支持回溯并可管理JSON数据的无限长字串流。jq支持基于名字空间的模块系统，并对闭包有一定支持，尤其是它的函数和泛函表达式可以用作其他函数的参数。

jq与Icon和Haskell编程语言有关。它最初采用Haskell实现^[3]，随即移植至C语言。gojq是“纯”Go实现。jq还有用Rust实现的叫做jaq的方言^[4]，它规定了指称语义^[5]。

历史

jq由Stephen Dolan创建并在2012年10月发行^[6]^[7] 。它被设计为“针对JSON数据的sed类似者”^[8]。在jq版本1.5中增加支持了正则表达式。

针对jq的叫做yq的“包装器”^[9]，增加支持了YAML、XML和TOML。它首次发行于2017年^[10]。

用Go实现的gojq最初发行于2019年^[11]，gojq显著的扩展jq包括了支持YAML。

用Rust实现的jaq，其项目目标是更快速和更准确的jq实现，仍保持与jq在大多数情况下的兼容性。在2024年3月于其目标中排除了jq的特定高级特征，比如模块、SQL风格算子和给非常大JSON文档的串流解析器^[4]。

用jq实现的jqjq，最初发行于2022年。jqjq显著的可以运行自身，拥有REPL并支持eval。

用法

命令行用法

jq典型的用于命令行，并可以协作于其他命令行实用工具，比如curl。下面的例子展示如何将curl命令的输出通过管道接转到jq过滤器（英语：Filter (software)），从而确定同这个Wikipedia页面关联的范畴名字：

$ URL=$(echo 'jq语言' | jq -rR '@uri "https://zh.wikipedia.org/w/api.php?action=parse&page=\(.)&format=json"')
$ curl -s ${URL} | jq '.parse.categories[]."*"'

这里的流水线产生的输出，由JSON字符串的串流组成，它们是：

"小寫標題"
"CS1英语来源_(en)"
"动态类型编程语言"
"函数式编程语言"
"面向文本编程语言"
"2012年建立的程式語言"
"数据查询语言"
"2012年软件"

上述curl命令对这个页面使用了MediaWiki API来产生JSON响应。管道（pipe）符号|允许curl的输出由jq来访问，它是标准的Unix shell的进程间通信机制^[12]。

这里展示的jq过滤器的方法链是如下流水线（pipeline）的简写：

.["parse"] | .["categories"] | .[] | .["*"]

这对应于curl调用所产生的嵌套JSON结构。jq流水线的构造方式，同Unix风格流水线一样，采用管道符号|。

嵌入式用法

C语言和Go实现二者都提供函数库，使得jq功能可以嵌入到其他应用和编程环境之中。

例如，gojq已经集成于SQLite，故而jq函数可以在其SQL语句中获得到^[13]。这些函数被标记为“确定性的”^[14]，故而可以被用在CREATE INDEX命令中^[15]。

运算的模态

jq缺省的充当针对JSON输入的“串流编辑器”，非常像被当作多行文本的“串流编辑器”的sed实用工具。但是jq有一些其他运算模态：

它可以将来自一个或多个来源的输入当作文本的诸行；
它可以将来自特定来源的输入的串流收集到一个JSON阵列之中；
它可以使用所谓的“串流解析器”解析其输入，产生针对所有“叶子”路径的[PATH, VALUE]阵列的串流。

“串流解析器”（streaming parser），在一个或多个JSON输入太大无法载入内存之时特别有用，因为它需求的内存典型的相当小。例如，对于任意大的JSON对象的阵列，峰值内存需求不比处理最大顶层对象所需要的多出很多。

这些运算模态可以在特定限制下组合起来。

语法和语义

类型

所有JSON值自身是jq中的值，它们从而有在下列表格中展示的类型^[16]。gojq和jaq实现将数区分为整数和浮点数。gojq实现支持无界精度整数算术，同于jq采用Haskell的最初实现。

jq支持的类型总结
类型	过滤器	例子
数	`numbers`	`3` `3.2` `1e6` `nan` `infinite`
字符串	`strings`	`"Hello"` `"😐"`
布尔值	`booleans`	`true` `false`
阵列	`arrays`	`[1, "2", {"mixed": "type"}, [3,4]]`
对象	`objects`	`{"one": 1, "two": "2", "three": [3]}`
空值	`nulls`	`null`

null是通常表示空值的一个值^[17]，就像任何其他JSON标量一样；它不是空指针。nan（对应于NaN）和infinite（参见IEEE 754），是仅有的两个不是JSON值的jq标量。

形式

jq有特殊语法形式，比如：

EXP as $var | ……：变量绑定；
PATH |= VALUE和PATH = VALUES：更新赋值和平凡（plain）赋值；
if …… then …… elif …… then …… else …… end：条件构造；
reduce EXP as $var (INIT; UPDATE)：串流归约；
foreach EXP as $var (INIT; UPDATE; EXTRACT)：输出中间值的串流归约；
def func : EXP;：函数创建；
include MOD;和import MOD as $name;：模块的包含和导入。

jq中有两种类型的符号，可称为“变量”的值绑定和函数。二者都是词法作用域的，表达式只能提及其左侧即前面最近的定义的符号，但是函数可以提及自身来创建递归函数。

过滤器

jq是面向JSON的编程语言，使用|符号来连接过滤器形成流水线。例如：

$ echo '[1,2]' | jq 'add'
3
$ jq -n '[1,2] | add'
3

这里jq内的JSON阵列[1,2]是求值为阵列的一个jq过滤器。

尽管类似于Unix流水线，jq流水线允许将到来数据，如同并行的发送到在|右手端的多于一个接收者。例如，程序add/length将计算阵列中数的平均，故而：

$ jq -n '[1,2] | add/length'
1.5
$ jq -nc '[1,2] | [length, add, add/length]'
[2,3,1.5]

单独的点号.可以充任占位符（placeholder）或通配符，例如：

$ jq -nc '1 | [., .]'
[1,1]
$ jq -n '2 | pow(.; .)'
4

在jq中采用隐式编程风格，阶乘可以通过共递归运算recurse()定义为[0,1] | recurse([first+1, last*(first+1)]) | last，下面是其使用例子：

$ echo '0 1 2 6' | jq -c '[limit(.+1; [0,1] | recurse([first+1, last*(first+1)]) | last)]'
[1]
[1,1]
[1,1,2]
[1,1,2,6,24,120,720]
$ jq -n 'first([0,1] | recurse([first+1, last*(first+1)]) | last)'
1
$ jq -n '[0,1,2,6][] | nth(.; [0,1] | recurse([first+1, last*(first+1)]) | last)'
1
1
2
720
$ jq -nc '[0,1,2,6] | map(nth(.; [0,1] | recurse([first+1, last*(first+1)]) | last))'
[1,1,2,720]

斐波那契数列可以通过共递归运算recurse()定义为[0,1] | recurse([last, add]) | first，下面是其使用例子：

$ echo '0 1 2 6' | jq -c '[limit(.+1; [0,1] | recurse([last, add]) | first)]'
[0]
[0,1]
[0,1,1]
[0,1,1,2,3,5,8]
$ jq -n 'first([0,1] | recurse([last, add]) | first)'
0
$ jq -n '[0,1,2,6][] | nth(.; [0,1] | recurse([last, add]) | first)'
0
1
1
8
$ jq -nc '[0,1,2,6] | map(nth(.; [0,1] | recurse([last, add]) | first))'
[0,1,1,8]

这种无限列表不可以不加限定的使用，也不可以对其进行last()运算。下面将其定义为新的命名过滤器：

def fac: nth(.; [0,1] | recurse([first+1, last*(first+1)]) | last);
def fib: nth(.; [0,1] | recurse([last, add]) | first);

共递归运算recurse()可以设置递推条件：

$ jq -nc '[0 | recurse(.+1; . < 0)]'
[0]
$ jq -nc '[0 | recurse(select(. < 0) | .+1)]'
[0]
$ jq -nc '[0 | recurse(.+1; . <= 6)]'
[0,1,2,3,4,5,6]
$ jq -nc '[0 | recurse(select(. < 6) | .+1)]'
[0,1,2,3,4,5,6]

下面的例子展示如何定义参数化的命名过滤器，它格式化从2到36含二者的任何底数的整数：

def tobase($b):
    def digit: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"[.:.+1];
    def mod: .%$b;
    def div: (.-mod)/$b;
    def place_values: recurse(select(. >= $b) | div) | mod;
    select(2 <= $b and $b <= 36)
    | [place_values | digit] | reverse | add;

这里的tobase($b)充当了库函数，所以为了应对使用者将.作为实际参数传递给它的潜在情况，而对其形式参数采用了变量形式。下面将它保存入tobase.jq文件，接着使用这个函数：

$ echo '15 16' | jq 'include "./tobase"; tobase(16)'
"F"
"10"

下一个例子求解经典的覆面算数学游戏：

{\begin{matrix}&&{\text{S}}&{\text{E}}&{\text{N}}&{\text{D}}\\+&&{\text{M}}&{\text{O}}&{\text{R}}&{\text{E}}\\\hline =&{\text{M}}&{\text{O}}&{\text{N}}&{\text{E}}&{\text{Y}}\\\end{matrix}}

从M是在最高位的进位可知：M为1，S为8或9，O为0，代码展示了基于range()和.[]的生成器：

def send_more_money:
    def choose(m; n; k): . as $used
        | ([range(m; n+1)]-[$used[]])[] | $used+{(k):.};
    def num: reduce .[] as $i (0; 10*. + $i);
    {"m":1,"o":0}
    | choose(8; 9; "s") | choose(2; 9; "e")
    | choose(2; 9; "n") | choose(2; 9; "d")
    | choose(2; 9; "r") | choose(2; 9; "y") 
    | select(([.s,.e,.n,.d] | num) 
        +    ([.m,.o,.r,.e] | num)
        ==([.m,.o,.n,.e,.y] | num))
    | [.s,.e,.n,.d,"+",.m,.o,.r,.e,"=",.m,.o,.n,.e,.y];
send_more_money

将上述代码保存入send_more_money.jq文件，接着使用这个函数得到这个谜题仅有的一个解：

$ jq -nc -f ./send_more_money.jq
[9,5,6,7,"+",1,0,8,5,"=",1,0,6,5,2]

解析表达式文法

在jq和解析表达式文法（PEG）形式化之间有密切关联^[18]。这种关联源于下列表格中展示的PEG七个基本运算与jq构造之间的等价性。

PEG运算与对应的jq等价者
PEG运算名字	PEG表示法	jq运算或过滤器定义
序列	`e1 e2`	`e1 \| e2`
有序选择	`e1 / e2`	`e1 // e2`
零或多个	`e*`	`def star(E): (E \| star(E)) // .;`
一或多个	`e+`	`def plus(E): E \| (plus(E) // .);`
可选	`e?`	`def optional(E): E // .;`
与断言	`&e`	`def amp(E): . as $in \| E \| $in;`
非断言	`!e`	`def neg(E): select([E] == []);`

八皇后问题例子

回溯法求解八皇后问题，采用函数式编程风格的条件表达式和递归函数可以写为：

def queens:
    def q(r): . as $pl
        | if r < 8 then
            $pl[3] as $cl | $cl[] | . as $c
            | (r+$c | tostring) as $k0
            | (r-$c | tostring) as $k1
            | def place:
                ($k0 | in($pl[1]) | not)
                and ($k1 | in($pl[2]) | not);
              select(place)
            | [$pl[0]+[$c], $pl[1]+{$k0:null},
                $pl[2]+{$k1:null}, $cl-[$c]]
            | q(r+1)
          else
            .[0] end;
    [[], {}, {}, [range(0; 8)]] | q(0)
    | map("abcdefgh"[.:.+1]) | to_entries
    | map(.value+(.key+1 | tostring)) | sort;
queens

	a	b	c	d	e	f	g	h
8									8
7									7
6									6
5									5
4									4
3									3
2									2
1									1
	a	b	c	d	e	f	g	h

解1

	a	b	c	d	e	f	g	h
8									8
7									7
6									6
5									5
4									4
3									3
2									2
1									1
	a	b	c	d	e	f	g	h

解2

将这段代码保存入queens.jq文件中，下面演示其执行结果并提取其92个解中的前两个解：

$ jq -nc -f ./queens.jq | wc -l
92
$ jq -nc -f ./queens.jq | sed -n '1,2p'
["a1","b7","c5","d8","e2","f4","g6","h3"]
["a1","b7","c4","d6","e8","f2","g5","h3"]

在能采用可逆（reversible）赋值和静态变量的语言比如Icon的实现中，其3个位置列表共有8+15+15 = 38个元素，而这个存储传递风格实现对3个位置列表进行了zip（英语：Zipping (computer science)）变换，共有3*8*(1+8)/2 = 108个元素。

进一步采用隐式编程风格，上述代码可以写为：

def queens:
   def q(r): . as $pl 
        | $pl[3] as $cl | $cl[] | . as $c
        | (r+$c | tostring) as $k0
        | (r-$c | tostring) as $k1
        | def place: 
            ($k0 | in($pl[1]) | not)
            and ($k1 | in($pl[2]) | not); 
          select(place)
        | [$pl[0]+[$c], $pl[1]+{$k0:null},
            $pl[2]+{$k1:null}, $cl-[$c]];
    def pipeline(i; n): 
        q(i) | if i+1 < n then pipeline(i+1; n) end;
    [[], {}, {}, [range(0; 8)]] | pipeline(0; 8) | .[0]
    | map("abcdefgh"[.:.+1]) | to_entries
    | map(.value+(.key+1 | tostring)) | sort;
queens

它还可以采用共递归运算recurse()写为：

def queens:
    def q: . as $pl 
        | $pl[4] as $r 
        | $pl[3] as $cl | $cl[] | . as $c
        | ($r+$c | tostring) as $k0
        | ($r-$c | tostring) as $k1
        | def place: 
            ($k0 | in($pl[1]) | not)
            and ($k1 | in($pl[2]) | not); 
          select(place)
        | [$pl[0]+[$c], $pl[1]+{$k0:null}, 
            $pl[2]+{$k1:null}, $cl-[$c], $r+1];
    [[], {}, {}, [range(0; 8)], 0] | recurse(q) 
    | select(.[4] == 8) | .[0]
    | map("abcdefgh"[.:.+1]) | to_entries
    | map(.value+(.key+1 | tostring)) | sort;
queens

最后，通过旋转和反射将可行解归并为独立解：

def queens(n):
    def q: . as $pl 
        | $pl[4] as $r 
        | $pl[3] as $cl | $cl[] | . as $c
        | ($r+$c | tostring) as $k0
        | ($r-$c | tostring) as $k1
        | def place: 
            ($k0 | in($pl[1]) | not)
            and ($k1 | in($pl[2]) | not); 
          select(place)
        | [$pl[0]+[$c], $pl[1]+{$k0:null},
            $pl[2]+{$k1:null}, $cl-[$c], $r+1];
    def pipeline(n): 
        q | if n > 1 then pipeline(n-1) end;
    def toletter: 
        "abcdefghijklmnopqrstuvwxyz"[.:.+1];
    def fund_solut(f):
        def inverse: . as $xl
            | reduce range(0; n) as $i
                ([]; .+[$xl | index($i)]);
        def variants:
            [., inverse] | map(., reverse)
            | map(., map(n-1-.)) 
            | map(map(toletter) | add);
        foreach f as $i 
            ([null, {}]; .[1] as $ml
            | ($i | variants) as $nl
            | if all($nl[]; in($ml) | not) then
                [$i, ($ml | .[$nl[]]=null)]
              else
                [null, $ml] end;
            .[0])
        | select (. != null);
    fund_solut([[], {}, {}, [range(0; n)], 0]
        | pipeline(n) | .[0]) 
    | map(toletter) | to_entries
    | map(.value+(.key+1 | tostring)) | sort;
queens(8)

下面演示其执行结果：

$ jq -nc -f ./queens.jq | wc -l
12
$ jq -nc -f ./queens.jq 
["a1","b7","c5","d8","e2","f4","g6","h3"]
["a1","b7","c4","d6","e8","f2","g5","h3"]
["a6","b1","c5","d2","e8","f3","g7","h4"]
["a4","b1","c5","d8","e2","f7","g3","h6"]
["a5","b1","c8","d4","e2","f7","g3","h6"]
["a3","b1","c7","d5","e8","f2","g4","h6"]
["a5","b1","c4","d6","e8","f2","g7","h3"]
["a7","b1","c3","d8","e6","f4","g2","h5"]
["a5","b1","c8","d6","e3","f7","g2","h4"]
["a5","b3","c1","d7","e2","f8","g6","h4"]
["a5","b7","c1","d4","e2","f8","g6","h3"]
["a6","b3","c1","d8","e4","f2","g7","h5"]

注释

^ jq的C或Go实现都没有任何运行时间依赖^[2]。
^ 包括Windows、Linux和macOS。Go实现可以在Go所支持的任何平台上编译^[2]。
^ jq的C实现，使用了叫做decNumber的十进制浮点数库，它采用了ICU许可证；和Oniguruma正则表达式库，它采用了BSD许可证^[2]。

参考书目

Janssens, Jeroen. Data Science at the Command Line. O'Reilly Media. 2021. ISBN 9781492087885 （英语）.
Janssens, Jeroen. Data Science at the Command Line: Facing the Future with Time-Tested Tools. O'Reilly Media. 2014. ISBN 9781491947807 （英语）.
Marrs, Tom. JSON at Work: Practical Data Integration for the Web. O'Reilly Media. 2017. ISBN 9781491982419 （英语）.

引用

^ Release jq 1.7.1.
^ ^2.0 ^2.1 ^2.2 Download jq. jq. [January 6, 2023]. （原始内容存档于2025-01-30）.
^ Initial · jqlang/Jq@eca89ac. GitHub. [2024-12-15]. （原始内容存档于2024-12-16）.
^ ^4.0 ^4.1 01mf02/jaq: A jq clone focussed on correctness, speed, and simplicity. GitHub. [March 6, 2024]. （原始内容存档于2025-01-16）.
^ Färber, Michael. Denotational Semantics and a fast interpreter for jq. 2023. arXiv:2302.10576  [cs.LO].
^ Janssens 2014.
^ jq. jq. [January 6, 2023]. （原始内容存档于2023-06-14）.
^ like sed. （原始内容存档于2013-04-14）.
^ yq. [2024-12-15]. （原始内容存档于2025-01-30）.
^ Release v2.0.0 · kislyuk/yq. GitHub. [2024-12-15]. （原始内容存档于2025-01-20）.
^ Release v0.0.1 · itchyny/gojq. GitHub. [2024-12-15]. （原始内容存档于2025-01-20）.
^ Tutorial. jq. [January 6, 2023]. （原始内容存档于2025-01-18）.
^ sqlite_jq. GitHub. [2024-12-15]. （原始内容存档于2023-01-08）.
^ "deterministic". [2024-12-15]. （原始内容存档于2024-12-27）.
^ FAQ. GitHub. [2024-12-15]. （原始内容存档于2025-01-26）.
^ Manual. jq. [January 6, 2023]. （原始内容存档于2025-01-30）.
^ Introducing JSON （页面存档备份，存于互联网档案馆）
^ PEG. PEG. [2024-12-15]. （原始内容存档于2025-01-20）.

外部链接

jq homepage （页面存档备份，存于互联网档案馆）
gojq （页面存档备份，存于互联网档案馆） - the Pure Go implementation
jaq （页面存档备份，存于互联网档案馆） - the Rust implementation
jqjq （页面存档备份，存于互联网档案馆） - the jq implementation
jq FAQ （页面存档备份，存于互联网档案馆）
Awesome jq （页面存档备份，存于互联网档案馆） - curated listing of jq-related resources
The jq Programming Language page （页面存档备份，存于互联网档案馆） on the Rosetta Code comparative programming tasks project site

[3] q的C或Go实现都没有任何运行时间依赖^[2]。

[4] 包括Windows、Linux和macOS。Go实现可以在Go所支持的任何平台上编译^[2]。

[5] q的C实现，使用了叫做decNumber的十进制浮点数库，它采用了ICU许可证；和Oniguruma正则表达式库，它采用了BSD许可证^[2]。

[wikidata-5ed9338ed4b21e53d443283c93be1a1d1f775995-v3-1] Release jq 1.7.1.

[Download-2] 2.0 ^2.1 ^2.2 Download jq. jq. [January 6, 2023]. （原始内容存档于2025-01-30）.

[6] Initial · jqlang/Jq@eca89ac. GitHub. [2024-12-15]. （原始内容存档于2024-12-16）.

[jaq-7] 4.0 ^4.1 01mf02/jaq: A jq clone focussed on correctness, speed, and simplicity. GitHub. [March 6, 2024]. （原始内容存档于2025-01-16）.

[Denotational_Semantics-8] Färber, Michael. Denotational Semantics and a fast interpreter for jq. 2023. arXiv:2302.10576  [cs.LO].

[FOOTNOTEJanssens2014-9] Janssens 2014.

[News-10] q. jq. [January 6, 2023]. （原始内容存档于2023-06-14）.

[archived-11] sed. （原始内容存档于2013-04-14）.

[12] yq. [2024-12-15]. （原始内容存档于2025-01-30）.

[xq_versions-13] Release v2.0.0 · kislyuk/yq. GitHub. [2024-12-15]. （原始内容存档于2025-01-20）.

[gojq-14] Release v0.0.1 · itchyny/gojq. GitHub. [2024-12-15]. （原始内容存档于2025-01-20）.

[Tutorial-15] Tutorial. jq. [January 6, 2023]. （原始内容存档于2025-01-18）.

[Maclean-16] sqlite_jq. GitHub. [2024-12-15]. （原始内容存档于2023-01-08）.

[17] "deterministic". [2024-12-15]. （原始内容存档于2024-12-27）.

[FAQ-18] FAQ. GitHub. [2024-12-15]. （原始内容存档于2025-01-26）.

[Manual-19] Manual. jq. [January 6, 2023]. （原始内容存档于2025-01-30）.

[20] Introducing JSON （页面存档备份，存于互联网档案馆）

[21] PEG. PEG. [2024-12-15]. （原始内容存档于2025-01-20）.

[1]

[a]

[b]

[c]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]

[16]

[17]

[18]

[2]