| jq | |
| Logo Caption: | The official jq logo |
| Logo Alt: | The characters "./jq" in black, monospace font |
| Paradigms: | Purely functional programming, JSON-oriented processing, tacit programming |
| Designer: | Stephen Dolan |
| Programming Language: | jq: C gojq: Go jaq: Rust jqjq: jq |
| Platform: | Cross-platform |
| Operating System: | Cross-platform |
| License: | MIT |
jq is a very high-level lexically scoped functional programming language in which every JSON value is a constant. jq supports backtracking and managing indefinitely long streams of JSON data. It is related to the Icon and Haskell programming languages. The language supports a namespace-based module system and has some support for closures. In particular, functions and functional expressions can be used as parameters of other functions.
The original implementation of jq was in Haskell[1] before being immediately ported to C.
jq was created by Stephen Dolan, and released in October 2012.[2] It was described as being "like sed for JSON data".[3] Support for regular expressions was added in jq version 1.5.
A "wrapper" program for jq named yq adds support for YAML, XML and TOML. It was first released in 2017.[4]
The Go implementation, gojq, was initially released in 2019.[5] gojq notably extends jq to include support for YAML.
The Rust implementation, jaq, has as its project goals a faster and more correct implementation of jq, while preserving compatibility with jq in most cases. Explicitly excluded from the project goals as of March 2024 are certain advanced features of jq such as modules, SQL-style operators, and a streaming parser for very large JSON documents.[6]
The jq implementation, jqjq, was initially released in 2022. jqjq notably can run itself, has a REPL and supports eval.
jq is typically used at the command line and can be used with other command-line utilities, such as curl. Here is an example showing how the output of a command can be piped to a jq filter to determine the category names associated with this Wikipedia page:
The command above uses the MediaWiki API for this page to produce a JSON response. The pipe allows the output of to be accessed by jq, a standard Unix shell mechanism.[7]
The jq filter shown is an abbreviation for the jq pipeline:
Both the C and the Go implementations provide libraries so that jq functionality can be embedded in other applications and programming environments.
For example, gojq has been integrated with SQLite so that a function is available in SQL statements.[8] This function is marked as"deterministic" andcan therefore be used in "CREATE INDEX" commands.[9]
jq by default acts as a "stream editor" for JSON inputs, muchlike the sed utility can be thought of as a "stream editor" for lines of text.However jq has several other modes of operation:
The "streaming parser" is particularly useful when one of more of theJSON inputs is too large to fit into memory, since its memory requirementsare typically quite small. For example, for an arbitrarily large array of JSON objects,the peak memory requirement is not much more than required to handle the largesttop-level object.
These modes of operation can, within certain limitations, be combined.
Every JSON value is itself a value in jq, which accordingly has the types shown in the table below.[10] The gojq and jaq implementations distinguish between integers and non-integer numbers. The gojq implementation supports unbounded-precision integer arithmetic, as did the original implementation of jq in Haskell.
| "number" | ||
| "string" | ||
| "boolean" | ||
| "array" | ||
| "object" | ||
| "null" |
is a value, just like any other JSON scalar; it is not a pointer or a "null-pointer". (corresponding to NaN) and (see IEEE 754) are the only two jq scalars that are not also JSON values.
There are special syntactic forms for function creation, conditionals, stream reduction, and the module system.
Here is an example which shows how to define a named, parameterized filter for formatting an integer in any basefrom 2 to 36 inclusive.The implementation illustrates tacit (or point-free) programming:
def tobase($b): def digit: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ"[.:.+1]; def mod: . % $b; def div: ((. - mod) / $b); def digits: recurse(select(. >= $b) | div) | mod ;
select(2 <= $b and $b <= 36) | [digits | digit] | reverse | add;
The next example demonstrates the use of generators in the classic "SEND MORE MONEY" verbal arithmetic game:
There is a very close relationship between jq and the parsing expression grammar (PEG) formalism.[11] The relationship stems from the equivalence of the seven basic PEG operations and the jq constructs shown in the following table.
| Sequence | e1 | e2 | ||
| Ordered choice | |||
| Zero-or-more | def star(E): (E | star(E)) // . ; | ||
| One-or-more | def plus(E): E | (plus(E) // .); | ||
| Optional | |||
| And-predicate | def amp(E): . as $in | E | $in; | ||
| Not-predicate |
gojq is a "pure Go" implementation. There is also a Rust implementation of a dialect of jq named jaq[6] for which a denotational semantics has been specified.[12]