jq Manual
-
A jq program is a “filter”: it takes an input, and produces an output. There are a lot of builtin filters for extracting a particular field of an object, or converting a number to a string, or various other standard tasks.
Filters can be combined in various ways - you can pipe the output of one filter into another filter, or collect the output of a filter into an array.
Some filters produce multiple results, for instance there’s one that produces all the elements of its input array. Piping that filter into a second runs the second filter for each element of the array. Generally, things that would be done with loops and iteration in other languages are just done by gluing filters together in jq.
It’s important to remember that every filter has an input and an output. Even literals like “hello” or 42 are filters - they take an input but always produce the same literal as output. Operations that combine two filters, like addition, generally feed the same input to both and combine the results. So, you can implement an averaging filter as add / length - feeding the input array both to the add filter and the length filter and dividing the results.
But that’s getting ahead of ourselves. :) Let’s start with something simpler:
+
A jq program is a “filter”: it takes an input, and produces an
+output. There are a lot of builtin filters for extracting a
+particular field of an object, or converting a number to a string,
+or various other standard tasks.
Filters can be combined in various ways – you can pipe the output of
+one filter into another filter, or collect the output of a filter
+into an array.
Some filters produce multiple results, for instance there’s one that
+produces all the elements of its input array. Piping that filter
+into a second runs the second filter for each element of the
+array. Generally, things that would be done with loops and iteration
+in other languages are just done by gluing filters together in jq.
It’s important to remember that every filter has an input and an
+output. Even literals like “hello” or 42 are filters – they take an
+input but always produce the same literal as output. Operations that
+combine two filters, like addition, generally feed the same input to
+both and combine the results. So, you can implement an averaging
+filter as add / length – feeding the input array both to the add
+filter and the length filter and dividing the results.
But that’s getting ahead of ourselves. :) Let’s start with something
+simpler:
Invoking jq
@@ -203,43 +231,51 @@
You can affect how jq reads and writes its input and output using some command-line options:
-Instead of running the filter for each JSON object in the
+input, read the entire input stream into a large array and run
+the filter just once.
-
---raw-input/-R
+* --raw-input/-R:
-Don’t parse the input as JSON. Instead, each line of text is passed to the filter as a string. If combined with --slurp, then the entire input is passed to the filter as a single long string.
-
+Don't parse the input as JSON. Instead, each line of text is
+passed to the filter as a string. If combined with `--slurp`,
+then the entire input is passed to the filter as a single long
+string.
-
---null-input/-n
+* --null-input/-n:
-Don’t read any input at all! Instead, the filter is run once using null as the input. This is useful when using jq as a simple calculator or to construct JSON data from scratch.
-
+Don't read any input at all! Instead, the filter is run once
+using `null` as the input. This is useful when using jq as a
+simple calculator or to construct JSON data from scratch.
-
---compact-output / -c
+* --compact-output / -c:
-By default, jq pretty-prints JSON output. Using this option will result in more compact output by instead putting each JSON object on a single line.
-
+By default, jq pretty-prints JSON output. Using this option
+will result in more compact output by instead putting each
+JSON object on a single line.
-
---ascii-output / -a
+* --colour-output / -C and --monochrome-output / -M:
-jq usually outputs non-ASCII Unicode codepoints as UTF-8, even if the input specified them as escape sequences (like “\u03bc”). Using this option, you can force jq to produce pure ASCII output with every non-ASCII character replaced with the equivalent escape sequence.
-
+By default, jq outputs colored JSON if writing to a
+terminal. You can force it to produce color even if writing to
+a pipe or a file using `-C`, and disable color with `-M`.
-
---raw-output / -r
+* --ascii-output / -a:
-With this option, if the filter’s result is a string then it will be written directly to standard output rather than being formatted as a JSON string with quotes. This can be useful for making jq filters talk to non-JSON-based systems.
-
-
+jq usually outputs non-ASCII Unicode codepoints as UTF-8, even
+if the input specified them as escape sequences (like
+"\u03bc"). Using this option, you can force jq to produce pure
+ASCII output with every non-ASCII character replaced with the
+equivalent escape sequence.
+
+* --raw-output / -r:
+
+With this option, if the filter's result is a string then it
+will be written directly to standard output rather than being
+formatted as a JSON string with quotes. This can be useful for
+making jq filters talk to non-JSON-based systems.
@@ -409,7 +445,7 @@
| jq '.[]' |
|---|
- | Input | [{name":"JSON", "good":true}, {"name":"XML", "good":false}] |
|---|
+ | Input | [{"name":"JSON", "good":true}, {"name":"XML", "good":false}] |
|---|
@@ -524,7 +560,7 @@
| Output |
- "d" |
+ "e" |
@@ -563,7 +599,7 @@
| jq '.[] | .name' |
|---|
- | Input | [{name":"JSON", "good":true}, {"name":"XML", "good":false}] |
|---|
+ | Input | [{"name":"JSON", "good":true}, {"name":"XML", "good":false}] |
|---|
@@ -772,17 +808,12 @@
| jq '.a + 1' |
|---|
| Input | {"a": 7} |
|---|
-
- | Output |
- none |
-
-
| Output |
- {"a": 8} |
+ 8 |
@@ -997,12 +1028,14 @@
The keys are sorted “alphabetically”, by unicode codepoint order. This is not an order that makes particular sense in any particular language, but you can count on it being the same for any two objects with the same set of keys, regardless of locale settings.
+When keys is given an array, it returns the valid indices for that array: the integers from 0 to length-1.
+
+
+ | jq 'keys' |
|---|
+ | Input | [42,3,35] |
|---|
+
+
+
+
+ | Output |
+
+ [0,1,2] |
+
+
+
+
+
@@ -1034,7 +1082,7 @@
The function select(foo) produces its input unchanged if foo returns true for that input, and produces no output otherwise.
-It’s useful for filtering lists: [1,2,3] | select(. >= 2) will give you [3].
+It’s useful for filtering lists: [1,2,3] | map(select(. >= 2)) will give you [3].
@@ -1047,7 +1095,7 @@
- | jq 'select(. >= 2)' |
|---|
+ | jq 'map(select(. >= 2))' |
|---|
| Input | [1,5,3,0,7] |
|---|
@@ -1094,7 +1142,14 @@
Output |
- 12 |
+ 1 |
+
+
+
+
+ |
+
+ 2 |
@@ -1187,7 +1242,7 @@
Output |
- abc |
+ "abc" |
@@ -1254,7 +1309,14 @@
Output |
- 11 |
+ 1 |
+
+
+
+
+ |
+
+ 1 |
@@ -1316,6 +1378,303 @@
+
+
+
sort, sort_by
+
+
+ The sort functions sorts its input, which must be an array. Values are sorted in the following order:
+
+
+nullfalsetrue- numbers
+
+- strings, in alphabetical order (by unicode codepoint value)
+
+- arrays, in lexical order
+
+- objects
+
+
+The ordering for objects is a little complex: first they’re compared by comparing their sets of keys (as arrays in sorted order), and if their keys are equal then the values are compared key by key.
+
+sort_by may be used to sort by a particular field of an object, or by applying any jq filter. sort_by(foo) compares two elements by comparing the result of foo on each element.
+
+
+
+
+
+
+ Examples
+
+
+
+
+
+ | jq 'sort' |
|---|
+ | Input | [8,3,null,6] |
|---|
+
+
+
+
+ | Output |
+
+ [null,3,6,8] |
+
+
+
+
+
+
+ | jq 'sort_by(.foo)' |
|---|
+ | Input | [{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}] |
|---|
+
+
+
+
+ | Output |
+
+ [{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}] |
+
+
+
+
+
+
+
+
group_by
+
+
+ group_by(.foo) takes as input an array, groups the elements having the same .foo field into separate arrays, and produces all of these arrays as elements of a larger array, sorted by the value of the .foo field.
+
+Any jq expression, not just a field access, may be used in place of .foo. The sorting order is the same as described in the sort function above.
+
+
+
+
+
+
+ Example
+
+
+
+
+
+ | jq 'group_by(.foo)' |
|---|
+ | Input | [{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}] |
|---|
+
+
+
+
+ | Output |
+
+ [[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]] |
+
+
+
+
+
+
+
+
min, max, min_by, max_by
+
+
+ Find the minimum or maximum element of the input array. The _by versions allow you to specify a particular field or property to examine, e.g. min_by(.foo) finds the object with the smallest foo field.
+
+
+
+
+
+
+ Examples
+
+
+
+
+
+ | jq 'min' |
|---|
+ | Input | [5,4,2,7] |
|---|
+
+
+
+
+ | Output |
+
+ 2 |
+
+
+
+
+
+
+ | jq 'max_by(.foo)' |
|---|
+ | Input | [{"foo":1, "bar":14}, {"foo":2, "bar":3}] |
|---|
+
+
+
+
+ | Output |
+
+ {"foo":2, "bar":3} |
+
+
+
+
+
+
+
+
unique
+
+
+ The unique function takes as input an array and produces an array of the same elements, in sorted order, with duplicates removed.
+
+
+
+
+
+
+ Example
+
+
+
+
+
+ | jq 'unique' |
|---|
+ | Input | [1,2,5,3,5,3,1,3] |
|---|
+
+
+
+
+ | Output |
+
+ [1,2,3,5] |
+
+
+
+
+
+
+
+
contains
+
+
+ The filter contains(b) will produce true if b is completely contained within the input. A string B is contained in a string A if B is a substring of A. An array B is contained in an array A is all elements in B are contained in any element in A. An object B is contained in object A if all of the values in B are contained in the value in A with the same key. All other types are assumed to be contained in each other if they are equal.
+
+
+
+
+
+
+ Examples
+
+
+
+
+
+ | jq 'contains("bar")' |
|---|
+ | Input | "foobar" |
|---|
+
+
+
+
+ | Output |
+
+ true |
+
+
+
+
+
+
+ | jq 'contains(["baz", "bar"])' |
|---|
+ | Input | ["foobar", "foobaz", "blarp"] |
|---|
+
+
+
+
+ | Output |
+
+ true |
+
+
+
+
+
+
+ | jq 'contains(["bazzzzz", "bar"])' |
|---|
+ | Input | ["foobar", "foobaz", "blarp"] |
|---|
+
+
+
+
+ | Output |
+
+ false |
+
+
+
+
+
+
+ | jq 'contains({foo: 12, bar: [{barp: 12}]})' |
|---|
+ | Input | {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]} |
|---|
+
+
+
+
+ | Output |
+
+ true |
+
+
+
+
+
+
+ | jq 'contains({foo: 12, bar: [{barp: 15}]})' |
|---|
+ | Input | {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]} |
|---|
+
+
+
+
+ | Output |
+
+ false |
+
+
+
+
+
+
+
String interpolation - \(foo)
@@ -1326,11 +1685,11 @@
-
+
Example
-
+
@@ -1371,11 +1730,11 @@
-
+
Example
-
+
@@ -1387,7 +1746,28 @@
| Output |
- [true, true, false, false] |
+ true |
+
+
+
+
+ |
+
+ true |
+
+
+
+
+ |
+
+ false |
+
+
+
+
+ |
+
+ false |
@@ -1414,11 +1794,11 @@
-
+
Example
-
+
@@ -1447,6 +1827,45 @@ end'
+
+
+
>, >=, <=, <
+
+
+ The comparison operators >, >=, <=, < return whether their left argument is greater than, greater than or equal to, less than or equal to or less than their right argument (respectively).
+
+The ordering is the same as that described for sort, above.
+
+
+
+
+
+
+ Example
+
+
+
+
+
+ | jq '. < 5' |
|---|
+ | Input | 2 |
|---|
+
+
+
+
+ | Output |
+
+ true |
+
+
+
+
+
+
+
and/or/not
@@ -1464,11 +1883,11 @@ not.
-
+
Examples
-
+
@@ -1576,11 +1995,11 @@ not.
-
+
Examples
-
+
@@ -1674,11 +2093,11 @@ not.
-
+
Example
-
+
@@ -1725,15 +2144,15 @@ not.
-
+
Examples
-
+
- | jq 'def addvalue(f): map(. + [$value]); addvalue(.[0])' |
|---|
+ | jq 'def addvalue(f): . + [f]; map(addvalue(.[0]))' |
|---|
| Input | [[1,2],[10,20]] |
|---|
@@ -1748,7 +2167,7 @@ not.
- | jq 'def addvalue(f): f as $x | map (. + $x); addvalue(.[0])' |
|---|
+ | jq 'def addvalue(f): f as $x | map(. + $x); addvalue(.[0])' |
|---|
| Input | [[1,2],[10,20]] |
|---|
@@ -1756,7 +2175,7 @@ not.
Output |
- [[1,2,[1,2]], [10,20,[1,2]]] |
+ [[1,2,1,2], [10,20,1,2]] |
@@ -1819,11 +2238,11 @@ not.
-
+
Example
-
+
@@ -1869,7 +2288,8 @@ not.
The paths provided by this operation point to each of the posts that “stedolan” wrote, and we can comment on each of them in the same way that we did before:
-(.posts[] | select(.author == "stedolan") | .comments) |= . + ["terrible."]
+(.posts[] | select(.author == "stedolan") | .comments) |=
+ . + ["terrible."]