jq

NAME

SYNOPSIS

FILTERS

INVOKING JQ

*

--version:

Output the jq version and exit with zero.

*

--seq:

Use the application/json-seq MIME type scheme for separating JSON texts in jq's input and output. This means that an ASCII RS (record separator) character is printed before each value on output and an ASCII LF (line feed) is printed after every output. Input JSON texts that fail to parse are ignored (but warned about), discarding all subsequent input until the next RS. This more also parses the output of jq without the --seq option.

*

--stream:

Parse the input in streaming fashion, outputing arrays of path and leaf values (scalars and empty arrays or empty objects). For example, "a" becomes [[],"a"], and [[],"a",["b"]] becomes [[0],[]], [[1],"a"], and [[1,0],"b"].

This is useful for processing very large inputs. Use this in conjunction with filtering and the reduce and foreach syntax to reduce large inputs incrementally.

*

--slurp/-s:

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:

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:

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:

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.

*

--tab:

Use a tab for each indentation level instead of two spaces.

*

--indent n:

Use the given number of spaces (no more than 8) for indentation.

*

--color-output / -C and --monochrome-output / -M:

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.

*

--ascii-output / -a:

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.

*

--unbuffered

Flush the output after each JSON object is printed (useful if you're piping a slow data source into jq and piping jq's output elsewhere).

*

--sort-keys / -S:

Output the fields of each object with the keys in sorted order.

*

--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.

*

--join-output / -j:

Like -r but jq won't print a newline after each output.

*

-f filename / --from-file filename:

Read filter from the file rather than from a command line, like awk's -f option. You can also use '#' to make comments.

*

-Ldirectory / -L directory:

Prepend directory to the search list for modules. If this option is used then no builtin search list is used. See the section on modules below.

*

-e / --exit-status:

Sets the exit status of jq to 0 if the last output values was neither false nor null, 1 if the last output value was either false or null, or 4 if no valid result was ever produced. Normally jq exits with 2 if there was any usage problem or system error, 3 if there was a jq program compile error, or 0 if the jq program ran.

*

--arg name value:

This option passes a value to the jq program as a predefined variable. If you run jq with --arg foo bar, then $foo is available in the program and has the value "bar". Note that value will be treated as a string, so --arg foo 123 will bind $foo to "123".

*

--argjson name JSON-text:

This option passes a JSON-encoded value to the jq program as a predefined variable. If you run jq with --argjson foo 123, then $foo is available in the program and has the value 123.

*

--slurpfile variable-name filename:

This option reads all the JSON texts in the named file and binds an array of the parsed JSON values to the given global variable. If you run jq with --argfile foo bar, then $foo is available in the program and has an array whose elements correspond to the texts in the file named bar.

*

--argfile variable-name filename:

Do not use. Use --slurpfile instead.

(This option is like --slurpfile, but when the file has just one text, then that is used, else an array of texts is used as in --slurpfile.)

*

--run-tests [filename]:

Runs the tests in the given file or standard input. This must be the last option given and does not honor all preceding options. The input consists of comment lines, empty lines, and program lines followed by one input line, as many lines of output as are expected (one per output), and a terminating empty line. Compilation failure tests start with a line containing only "%%FAIL", then a line containing the program to compile, then a line containing an error message to compare to the actual.

Be warned that this option can change backwards-incompatibly.

BASIC FILTERS

.

jq '.'
   "Hello, world!"
=> "Hello, world!"

.foo, .foo.bar

jq '.foo'
   {"foo": 42, "bar": "less interesting data"}
=> 42

jq '.foo'
   {"notfoo": true, "alsonotfoo": false}
=> null

jq '.["foo"]'
   {"foo": 42}
=> 42

.foo?

jq '.foo?'
   {"foo": 42, "bar": "less interesting data"}
=> 42

jq '.foo?'
   {"notfoo": true, "alsonotfoo": false}
=> null

jq '.["foo"]?'
   {"foo": 42}
=> 42

jq '[.foo?]'
   [1,2]
=> []

.[<string>], .[2], .[10:15]

jq '.[0]'
   [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> {"name":"JSON", "good":true}

jq '.[2]'
   [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> null

jq '.[2:4]'
   ["a","b","c","d","e"]
=> ["c", "d"]

jq '.[2:4]'
   "abcdefghi"
=> "cd"

jq '.[:3]'
   ["a","b","c","d","e"]
=> ["a", "b", "c"]

jq '.[-2:]'
   ["a","b","c","d","e"]
=> ["d", "e"]

jq '.[-2]'
   [1,2,3]
=> 2

.[]

jq '.[]'
   [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> {"name":"JSON", "good":true}, {"name":"XML", "good":false}

jq '.[]'
   []
=>

jq '.[]'
   {"a": 1, "b": 1}
=> 1, 1

.[]?

,

jq '.foo, .bar'
   {"foo": 42, "bar": "something else", "baz": true}
=> 42, "something else"

jq '.user, .projects[]'
   {"user":"stedolan", "projects": ["jq", "wikiflow"]}
=> "stedolan", "jq", "wikiflow"

jq '.[4,2]'
   ["a","b","c","d","e"]
=> "e", "c"

|

jq '.[] | .name'
   [{"name":"JSON", "good":true}, {"name":"XML", "good":false}]
=> "JSON", "XML"

TYPES AND VALUES

Array construction - []

jq '[.user, .projects[]]'
   {"user":"stedolan", "projects": ["jq", "wikiflow"]}
=> ["stedolan", "jq", "wikiflow"]

Objects - {}

{foo: .bar}

will produce the JSON object {"foo": 42} if given the JSON object {"bar":42, "baz":43}. You can use this to select particular fields of an object: if the input is an object with "user", "title", "id", and "content" fields and you just want "user" and "title", you can write

{user: .user, title: .title}

Because that's so common, there's a shortcut syntax: {user, title}. If one of the expressions produces multiple results, multiple dictionaries will be produced. If the input's

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

then the expression

{user, title: .titles[]}

will produce two outputs:

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

Putting parentheses around the key means it will be evaluated as an expression. With the same input as above,

{(.user): .titles}

produces

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

jq '{user, title: .titles[]}'
   {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
=> {"user":"stedolan", "title": "JQ Primer"}, {"user":"stedolan", "title": "More JQ"}

jq '{(.user): .titles}'
   {"user":"stedolan","titles":["JQ Primer", "More JQ"]}
=> {"stedolan": ["JQ Primer", "More JQ"]}

BUILTIN OPERATORS AND FUNCTIONS

Addition - +

*

Numbers are added by normal arithmetic.

*

Arrays are added by being concatenated into a larger array.

*

Strings are added by being joined into a larger string.

*

Objects are added by merging, that is, inserting all the key-value pairs from both objects into a single combined object. If both objects contain a value for the same key, the object on the right of the + wins. (For recursive merge use the * operator.)

null can be added to any value, and returns the other value unchanged.

jq '.a + 1'
   {"a": 7}
=> 8

jq '.a + .b'
   {"a": [1,2], "b": [3,4]}
=> [1,2,3,4]

jq '.a + null'
   {"a": 1}
=> 1

jq '.a + 1'
   {}
=> 1

jq '{a: 1} + {b: 2} + {c: 3} + {a: 42}'
   null
=> {"a": 42, "b": 2, "c": 3}

Subtraction - -

jq '4 - .a'
   {"a":3}
=> 1

jq '. - ["xml", "yaml"]'
   ["xml", "yaml", "json"]
=> ["json"]

Multiplication, division, modulo - *, /, and %

jq '10 / . * 3'
   5
=> 6

jq '. / ", "'
   "a, b,c,d, e"
=> ["a","b,c,d","e"]

jq '{"k": {"a": 1, "b": 2}} * {"k": {"a": 0,"c": 3}}'
   null
=> {"k": {"a": 0, "b": 2, "c": 3}}

jq '.[] | (1 / .)?'
   [1,0,-1]
=> 1, -1

length

*

The length of a string 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).

*

The length of an array is the number of elements.

*

The length of an object is the number of key-value pairs.

*

The length of null is zero.

jq '.[] | length' [[1,2], "string", {"a":2}, null] => 2, 6, 1, 0

keys, keys_unsorted

jq 'keys'
   {"abc": 1, "abcd": 2, "Foo": 3}
=> ["Foo", "abc", "abcd"]

jq 'keys'
   [42,3,35]
=> [0,1,2]

has(key)

jq 'map(has("foo"))'
   [{"foo": 42}, {}]
=> [true, false]

jq 'map(has(2))'
   [[0,1], ["a","b","c"]]
=> [false, true]

in

jq '.[] | in({"foo": 42})'
   ["foo", "bar"]
=> true, false

jq 'map(in([0,1]))'
   [2, 0]
=> [false, true]

path(path_expression)

jq 'path(.a[0].b)'
   null
=> ["a",0,"b"]

jq '[path(..)]'
   {"a":[{"b":1}]}
=> [[],["a"],["a",0],["a",0,"b"]]

del(path_expression)

jq 'del(.foo)'
   {"foo": 42, "bar": 9001, "baz": 42}
=> {"bar": 9001, "baz": 42}

jq 'del(.[1, 2])'
   ["foo", "bar", "baz"]
=> ["foo"]

to_entries, from_entries, with_entries

jq 'to_entries'
   {"a": 1, "b": 2}
=> [{"key":"a", "value":1}, {"key":"b", "value":2}]

jq 'from_entries'
   [{"key":"a", "value":1}, {"key":"b", "value":2}]
=> {"a": 1, "b": 2}

jq 'with_entries(.key |= "KEY_" + .)'
   {"a": 1, "b": 2}
=> {"KEY_a": 1, "KEY_b": 2}

select(boolean_expression)

jq 'map(select(. >= 2))'
   [1,5,3,0,7]
=> [5,3,7]

jq '.[] | select(.id == "second")'
   [{"id": "first", "val": 1}, {"id": "second", "val": 2}]
=> {"id": "second", "val": 2}

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

jq '.[]|numbers'
   [[],{},1,"foo",null,true,false]
=> 1

empty

jq '1, empty, 2'
   null
=> 1, 2

jq '[1,2,empty,3]'
   null
=> [1,2,3]

error(message)

$__loc__

jq 'try error("\($__loc__)") catch .'
   null
=> "{\"file\":\"<top-level>\",\"line\":1}"

map(x), map_values(x)

jq 'map(.+1)'
   [1,2,3]
=> [2,3,4]

jq 'map_values(.+1)'
   {"a": 1, "b": 2, "c": 3}
=> {"a": 2, "b": 3, "c": 4}

paths, paths(node_filter), leaf_paths

jq '[paths]'
   [1,[[],{"a":2}]]
=> [[0],[1],[1,0],[1,1],[1,1,"a"]]

jq '[paths(scalars)]'
   [1,[[],{"a":2}]]
=> [[0],[1,1,"a"]]

add

jq 'add'
   ["a","b","c"]
=> "abc"

jq 'add'
   [1, 2, 3]
=> 6

jq 'add'
   []
=> null

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

jq 'any'
   [true, false]
=> true

jq 'any'
   [false, false]
=> false

jq 'any'
   []
=> false

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

jq 'all'
   [true, false]
=> false

jq 'all'
   [true, true]
=> true

jq 'all'
   []
=> true

[Requires 1.5] flatten, flatten(depth)

jq 'flatten'
   [1, [2], [[3]]]
=> [1, 2, 3]

jq 'flatten(1)'
   [1, [2], [[3]]]
=> [1, 2, [3]]

jq 'flatten'
   [[]]
=> []

jq 'flatten'
   [{"foo": "bar"}, [{"foo": "baz"}]]
=> [{"foo": "bar"}, {"foo": "baz"}]

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

jq 'range(2;4)'
   null
=> 2, 3

jq '[range(2;4)]'
   null
=> [2,3]

jq '[range(4)]'
   null
=> [0,1,2,3]

jq '[range(0;10;3)]'
   null
=> [0,3,6,9]

jq '[range(0;10;-1)]'
   null
=> []

jq '[range(0;-5;-1)]'
   null
=> [0,-1,-2,-3,-4]

floor

jq 'floor'
   3.14159
=> 3

sqrt

jq 'sqrt'
   9
=> 3

tonumber

jq '.[] | tonumber'
   [1, "1"]
=> 1, 1

tostring

jq '.[] | tostring'
   [1, "1", [1]]
=> "1", "1", "[1]"

type

jq 'map(type)'
   [0, false, [], {}, null, "hello"]
=> ["number", "boolean", "array", "object", "null", "string"]

infinite, nan, isinfinite, isnan, isfinite, isnormal

jq '.[] | (infinite * .) < 0'
   [-1, 1]
=> true, false

jq 'infinite, nan | type'
   null
=> "number", "number"

sort, sort_by(path_expression)

*

null

*

false

*

true

*

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 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.

jq 'sort'
   [8,3,null,6]
=> [null,3,6,8]

jq 'sort_by(.foo)'
   [{"foo":4, "bar":10}, {"foo":3, "bar":100}, {"foo":2, "bar":1}]
=> [{"foo":2, "bar":1}, {"foo":3, "bar":100}, {"foo":4, "bar":10}]

group_by(path_expression)

jq 'group_by(.foo)'
   [{"foo":1, "bar":10}, {"foo":3, "bar":100}, {"foo":1, "bar":1}]
=> [[{"foo":1, "bar":10}, {"foo":1, "bar":1}], [{"foo":3, "bar":100}]]

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

jq 'min'
   [5,4,2,7]
=> 2

jq 'max_by(.foo)'
   [{"foo":1, "bar":14}, {"foo":2, "bar":3}]
=> {"foo":2, "bar":3}

unique, unique_by(path_exp)

jq 'unique'
   [1,2,5,3,5,3,1,3]
=> [1,2,3,5]

jq 'unique_by(.foo)'
   [{"foo": 1, "bar": 2}, {"foo": 1, "bar": 3}, {"foo": 4, "bar": 5}]
=> [{"foo": 1, "bar": 2}, {"foo": 4, "bar": 5}]

jq 'unique_by(length)'
   ["chunky", "bacon", "kitten", "cicada", "asparagus"]
=> ["bacon", "chunky", "asparagus"]

reverse

jq 'reverse'
   [1,2,3,4]
=> [4,3,2,1]

contains(element)

jq 'contains("bar")'
   "foobar"
=> true

jq 'contains(["baz", "bar"])'
   ["foobar", "foobaz", "blarp"]
=> true

jq 'contains(["bazzzzz", "bar"])'
   ["foobar", "foobaz", "blarp"]
=> false

jq 'contains({foo: 12, bar: [{barp: 12}]})'
   {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}
=> true

jq 'contains({foo: 12, bar: [{barp: 15}]})'
   {"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]}
=> false

indices(s)

jq 'indices(", ")'
   "a,b, cd, efg, hijk"
=> [3,7,12]

jq 'indices(1)'
   [0,1,2,1,3,1,4]
=> [1,3,5]

jq 'indices([1,2])'
   [0,1,2,3,1,4,2,5,1,2,6,7]
=> [1,8]

index(s), rindex(s)

jq 'index(", ")'
   "a,b, cd, efg, hijk"
=> 3

jq 'rindex(", ")'
   "a,b, cd, efg, hijk"
=> 12

inside

jq 'inside("foobar")'
   "bar"
=> true

jq 'inside(["foobar", "foobaz", "blarp"])'
   ["baz", "bar"]
=> true

jq 'inside(["foobar", "foobaz", "blarp"])'
   ["bazzzzz", "bar"]
=> false

jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'
   {"foo": 12, "bar": [{"barp": 12}]}
=> true

jq 'inside({"foo": 12, "bar":[1,2,{"barp":12, "blip":13}]})'
   {"foo": 12, "bar": [{"barp": 15}]}
=> false

startswith(str)

jq '[.[]|startswith("foo")]'
   ["fo", "foo", "barfoo", "foobar", "barfoob"]
=> [false, true, false, true, false]

endswith(str)

jq '[.[]|endswith("foo")]'
   ["foobar", "barfoo"]
=> [false, true]

combinations, combinations(n)

jq 'combinations'
   [[1,2], [3, 4]]
=> [1, 3], [1, 4], [2, 3], [2, 4]

jq 'combinations(2)'
   [0, 1]
=> [0, 0], [0, 1], [1, 0], [1, 1]

ltrimstr(str)

jq '[.[]|ltrimstr("foo")]'
   ["fo", "foo", "barfoo", "foobar", "afoo"]
=> ["fo","","barfoo","bar","afoo"]

rtrimstr(str)

jq '[.[]|rtrimstr("foo")]'
   ["fo", "foo", "barfoo", "foobar", "foob"]
=> ["fo","","bar","foobar","foob"]

explode

jq 'explode'
   "foobar"
=> [102,111,111,98,97,114]

implode

jq 'implode'
   [65, 66, 67]
=> "ABC"

split

jq 'split(", ")'
   "a, b,c,d, e, "
=> ["a","b,c,d","e",""]

join(str)

jq 'join(", ")'
   ["a","b,c,d","e"]
=> "a, b,c,d, e"

ascii_downcase, ascii_upcase

while(cond; update)

jq '[while(.<100; .*2)]'
   1
=> [1,2,4,8,16,32,64]

until(cond; next)

jq '[.,1]|until(.[0] < 1; [.[0] - 1, .[1] * .[0]])|.[1]'
   4
=> 24

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

{"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": []}]}]}]}

Now suppose you want to extract all of the filenames present. You need to retrieve .name, .children[].name, .children[].children[].name, and so on. You can do this with:

recurse(.children[]) | .name

When called without an argument, recurse is equivalent to recurse(.[]?). recurse(f) is identical to recurse(f; . != null) and can be used without concerns about recursion depth. recurse(f; condition) is a generator which begins by emitting . and then emits in turn .|f, .|f|f, .|f|f|f, ... so long as the computed value satisfies the condition. For example, to generate all the integers, at least in principle, one could write recurse(.+1; true). For legacy reasons, recurse_down exists as an alias to calling recurse without arguments. This alias is considered deprecated and will be removed in the next major release. The recursive calls in recurse will not consume additional memory whenever f produces at most a single output for each input.

jq 'recurse(.foo[])'
   {"foo":[{"foo": []}, {"foo":[{"foo":[]}]}]}
=> {"foo":[{"foo":[]},{"foo":[{"foo":[]}]}]}, {"foo":[]}, {"foo":[{"foo":[]}]}, {"foo":[]}

jq 'recurse'
   {"a":0,"b":[1]}
=> {"a":0,"b":[1]}, 0, [1], 1

jq 'recurse(. * .; . < 20)'
   2
=> 2, 4, 16

..

jq '..|.a?'
   [[{"a":1}]]
=> 1

env

jq 'env.PAGER'
   null
=> "less"

transpose

jq 'transpose'
   [[1], [2,3]]
=> [[1,2],[null,3]]

bsearch(x)

jq 'bsearch(0)'
   [0,1]
=> 0

jq 'bsearch(0)'
   [1,2,3]
=> -1

jq 'bsearch(4) as $ix | if $ix < 0 then .[-(1+$ix)] = 4 else . end'
   [1,2,3]
=> [1,2,3,4]

String interpolation - \(foo)

jq '"The input was \(.), which is one less than \(.+1)"'
   42
=> "The input was 42, which is one less than 43"

Convert to/from JSON

jq '[.[]|tostring]'
   [1, "foo", ["foo"]]
=> ["1","foo","[\"foo\"]"]

jq '[.[]|tojson]'
   [1, "foo", ["foo"]]
=> ["1","\"foo\"","[\"foo\"]"]

jq '[.[]|tojson|fromjson]'
   [1, "foo", ["foo"]]
=> [1,"foo",["foo"]]

Format strings and escaping

@text:

Calls tostring, see that function for details.

@json:

Serializes the input as JSON.

@html:

Applies HTML/XML escaping, by mapping the characters <>&'" to their entity equivalents &lt;, &gt;, &amp;, &apos;, &quot;.

@uri:

Applies percent-encoding, by mapping all reserved URI characters to a %XX sequence.

@csv:

The input must be an array, and it is rendered as CSV with double quotes for strings, and quotes escaped by repetition.

@tsv:

The input must be an array, and it is rendered as TSV (tab-separated values). Each input array will be printed as a single line. Fields are separated by a single tab (ascii 0x09). 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:

The input is converted to base64 as specified by RFC 4648. This syntax can be combined with string interpolation in a useful way. You can follow a @foo token with a string literal. The contents of the string literal will not be escaped. However, all interpolations made inside that string literal will be escaped. For instance,

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

will produce the following output for the input {"search":"what is jq?"}:

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

Note that the slashes, question mark, etc. in the URL are not escaped, as they were part of the string literal.

jq '@html'
   "This works if x < y"
=> "This works if x &lt; y"

jq '@sh "echo \(.)"'
   "O'Hara's Ale"
=> "echo 'O'\\''Hara'\\''s Ale'"

Dates

jq 'fromdate'
   "2015-03-05T23:51:47Z"
=> 1425599507

jq 'strptime("%Y-%m-%dT%H:%M:%SZ")'
   "2015-03-05T23:51:47Z"
=> [2015,2,5,23,51,47,4,63]

jq 'strptime("%Y-%m-%dT%H:%M:%SZ")|mktime'
   "2015-03-05T23:51:47Z"
=> 1425599507

CONDITIONALS AND COMPARISONS

==, !=

jq '.[] == 1'
   [1, 1.0, "1", "banana"]
=> true, true, false, false

if-then-else

jq 'if . == 0 then

"zero" elif . == 1 then "one" else "many" end' 2 => "many"

>, >=, <=, <

jq '. < 5'
   2
=> true

and/or/not

jq '42 and "a string"'
   null
=> true

jq '(true, false) or false'
   null
=> true, false

jq '(true, true) and (true, false)'
   null
=> true, false, true, false

jq '[true, false | not]'
   null
=> [false, true]

Alternative operator - //

jq '.foo // 42'
   {"foo": 19}
=> 19

jq '.foo // 42'
   {}
=> 42

try-catch

jq 'try .a catch ". is not an object"'
   true
=> ". is not an object"

jq '[.[]|try .a]'
   [{}, true, {"a":1}]
=> [null, 1]

jq 'try error("some exception") catch .'
   true
=> "some exception"

Breaking out of control structures

# 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 .=="break" then empty else error;

jq has a syntax for named lexical labels to "break" or "go (back) to":

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

The break $label_name expression will cause the program to to act as though the nearest (to the left) label $label_name produced empty. The relationship between the break and corresponding label is lexical: the label has to be "visible" from the break. To break out of a reduce, for example:

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

The following jq program produces a syntax error:

break $out

because no label $out is visible.

? operator

jq '[.[]|(.a)?]'
   [{}, true, {"a":1}]
=> [null, 1]

REGULAR EXPRESSIONS (PCRE)

STRING | FILTER( REGEX )
STRING | FILTER( REGEX; FLAGS )
STRING | FILTER( [REGEX] )
STRING | FILTER( [REGEX, FLAGS] )

where: * STRING, REGEX and FLAGS are jq strings and subject to jq string interpolation; * REGEX, after string interpolation, should be a valid PCRE regex; * FILTER is one of test, match, or capture, as described below. FLAGS is a string consisting of one of more of the supported flags:

*

g - Global search (find all matches, not just the first)

*

i - Case insensitive search

*

m - Multi line mode ('.' will match newlines)

*

n - Ignore empty matches

*

p - Both s and m modes are enabled

*

s - Single line mode ('^' -> '\A', '$' -> '\Z')

*

l - Find longest possible matches

*

x - Extended regex format (ignore whitespace and comments)

To match whitespace in an x pattern use an escape such as \s, e.g.

*

test( "a\sb", "x" ).

Note that certain flags may also be specified within REGEX, e.g.

*

jq -n '("test", "TEst", "teST", "TEST") | test( "(?i)te(?-i)st" )'

evaluates to: true, true, false, false.

[Requires 1.5] test(val), test(regex; flags)

jq 'test("foo")'
   "foo"
=> true

jq '.[] | test("a b c # spaces are ignored"; "ix")'
   ["xabcd", "ABC"]
=> true, true

[Requires 1.5] match(val), match(regex; flags)

*

offset - offset in UTF-8 codepoints from the beginning of the input

*

length - length in UTF-8 codepoints of the match

*

string - the string that it matched

*

captures - an array of objects representing capturing groups.

Capturing group objects have the following fields:

*

offset - offset in UTF-8 codepoints from the beginning of the input

*

length - length in UTF-8 codepoints of this capturing group

*

string - the string that was captured

*

name - the name of the capturing group (or null if it was unnamed)

Capturing groups that did not match anything return an offset of -1

jq 'match("(abc)+"; "g")'
   "abc abc"
=> {"offset": 0, "length": 3, "string": "abc", "captures": [{"offset": 0, "length": 3, "string": "abc", "name": null}]}, {"offset": 4, "length": 3, "string": "abc", "captures": [{"offset": 4, "length": 3, "string": "abc", "name": null}]}

jq 'match("foo")'
   "foo bar foo"
=> {"offset": 0, "length": 3, "string": "foo", "captures": []}

jq 'match(["foo", "ig"])'
   "foo bar FOO"
=> {"offset": 0, "length": 3, "string": "foo", "captures": []}, {"offset": 8, "length": 3, "string": "FOO", "captures": []}

jq 'match("foo (?<bar123>bar)? foo"; "ig")'
   "foo bar foo foo  foo"
=> {"offset": 0, "length": 11, "string": "foo bar foo", "captures": [{"offset": 4, "length": 3, "string": "bar", "name": "bar123"}]}, {"offset": 12, "length": 8, "string": "foo  foo", "captures": [{"offset": -1, "length": 0, "string": null, "name": "bar123"}]}

jq '[ match("."; "g")] | length'
   "abc"
=> 3

[Requires 1.5] capture(val), capture(regex; flags)

jq 'capture("(?<a>[a-z]+)-(?<n>[0-9]+)")'
   "xyzzy-14"
=> { "a": "xyzzy", "n": "14" }

[Requires 1.5] scan(regex), scan(regex; flags)

split(regex; flags)

[Requires 1.5] splits(regex), splits(regex; flags)

[Requires 1.5] sub(regex; tostring) sub(regex; string; flags)

[Requires 1.5] gsub(regex; string), gsub(regex; string; flags)

ADVANCED FEATURES

Variables

length as $array_length | add / $array_length

We'll need a more complicated problem to find a situation where using variables actually makes our lives easier. Suppose we have an array of blog posts, with "author" and "title" fields, and another object which is used to map author usernames to real names. Our input looks like:

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

We want to produce the posts with the author field containing a real name, as in:

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

We use a variable, $names, to store the realnames object, so that we can refer to it later when looking up author usernames:

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

The expression exp as $x | ... means: for each value of expression exp, run the rest of the pipeline with the entire original input, and with $x set to that value. Thus as functions as something of a foreach loop. Just as {foo} is a handy way of writing {foo: .foo}, so {$foo} is a handy way of writing {foo:$foo}. Multiple variables may be declared using a single as expression by providing a pattern that matches the structure of the input (this is known as "destructuring"):

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

The variable declarations in array patterns (e.g., . as [$first, $second]) bind to the elements of the array in from the element at index zero on up, in order. When there is no value at the index for an array pattern element, null is bound to that variable. Variables are scoped over the rest of the expression that defines them, so

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

will work, but

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

won't. For programming language theorists, it's more accurate to say that jq variables are lexically-scoped bindings. In particular there's no way to change the value of a binding; one can only setup a new binding with the same name, but which will not be visible where the old one was.

jq '.bar as $x | .foo | . + $x'
   {"foo":10, "bar":200}
=> 210

jq '. as $i|[(.*2|. as $i| $i), $i]'
   5
=> [10,5]

jq '. as [$a, $b, {c: $c}] | $a + $b + $c'
   [2, 3, {"c": 4, "d": 5}]
=> 9

jq '.[] as [$a, $b] | {a: $a, b: $b}'
   [[0], [0, 1], [2, 1, 0]]
=> {"a":0,"b":null}, {"a":0,"b":1}, {"a":2,"b":1}

Defining Functions

def increment: . + 1;

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

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

Arguments are passed as filters, 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. 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.

jq 'def addvalue(f): . + [f]; map(addvalue(.[0]))'
   [[1,2],[10,20]]
=> [[1,2,1], [10,20,10]]

jq 'def addvalue(f): f as $x | map(. + $x); addvalue(.[0])'
   [[1,2],[10,20]]
=> [[1,2,1,2], [10,20,1,2]]

Reduce

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

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

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

jq 'reduce .[] as $item (0; . + $item)'
   [10,2,5,3]
=> 20

limit(n; exp)

jq '[limit(3;.[])]'
   [0,1,2,3,4,5,6,7,8,9]
=> [0,1,2]

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

jq '[first(range(.)), last(range(.)), nth(./2; range(.))]'
   10
=> [0,9,5]

first, last, nth(n)

jq '[range(.)]|[first, last, nth(5)]'
   10
=> [0,9,5]

foreach

jq '[foreach .[] as $item ([[],[]]; if $item == null then [[],.[0]] else [(.[0] + [$item]),[]] end; if $item == null then .[1] else empty end)]'
   [1,2,3,4,null,"a","b",null]
=> [[1,2,3,4],["a","b"]]

Recursion

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;

Generators and iterators

jq 'def range(init; upto; by): def _range: if (by > 0 and . < upto) or (by < 0 and . > upto) then ., ((.+by)|_range) else . end; if by == 0 then init else init|_range end | select((by > 0 and . < upto) or (by < 0 and . > upto)); range(0; 10; 3)'
   null
=> 0, 3, 6, 9

jq 'def while(cond; update): def _while: if cond then ., (update | _while) else empty end; _while; [while(.<100; .*2)]'
   1
=> [1,2,4,8,16,32,64]

MATH

I/O

input

inputs

debug

input_filename

input_line_number

STREAMING

truncate_stream(stream_expression)

jq '[1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]])]'
   1
=> [[[0],2],[[0]]]

fromstream(stream_expression)

jq 'fromstream(1|truncate_stream([[0],1],[[1,0],2],[[1,0]],[[1]]))'
   null
=> [2]

tostream

jq '. as $dot|fromstream($dot|tostream)|.==$dot'
   [0,[1,{"a":1},{"b":2}]]
=> true

ASSIGNMENT

=

|=

jq '(..|select(type=="boolean")) |= if . then 1 else 0 end'
   [true,false,[5,true,[true,[false]],false]]
=> [1,0,[5,1,[1,[0]],0]]

+=, -=, *=, /=, %=, //=

jq '.foo += 1'
   {"foo": 42}
=> {"foo": 43}

Complex assignments

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

What may come as a surprise is that the expression on the left may produce multiple results, referring to different points in the input document:

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

That example appends the string "this is great" to the "comments" array of each post in the input (where the input is an object with a field "posts" which is an array of posts). When jq encounters an assignment like 'a = b', it records the "path" taken to select a part of the input document while executing a. This path is then used to find which part of the input to change while executing the assignment. Any filter may be used on the left-hand side of an equals - whichever paths it selects from the input will be where the assignment is performed. This is a very powerful operation. Suppose we wanted to add a comment to blog posts, using the same "blog" input above. This time, we only want to comment on the posts written by "stedolan". We can find those posts using the "select" function described earlier:

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

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."]

MODULES

import RelativePathString as NAME [<metadata>];

include RelativePathString [<metadata>];

import RelativePathString as $NAME [<metadata>];

module <metadata>;

modulemeta

BUGS

https://github.com/stedolan/jq/issues

AUTHOR