jq reads JSON, passes it through a filter and prints the result. A filter is a small program: . is the whole document, .field is a field's value, | passes the result on, as in the shell. A filter can produce zero, one or many values — each is printed separately.
Syntax
jq [options] 'filter' [file…]
jq [options] -f program.jq [file…]
Without a file it reads stdin. Always put the filter in single quotes, otherwise the shell will mangle $, | and quotes inside it.
Output options
| Option | What it does |
|---|
-r | strings without quotes and escaping — for further processing in the shell |
-j | like -r, but without a newline after each value |
-c | compact: each result on one line |
-S | sort object keys |
--tab / --indent N | indent with a tab / N spaces |
-a | non-ASCII characters as \uXXXX |
-C / -M | force color on / off |
-e | exit code based on the result: 1 if the last value is null or false; 4 if there's no result |
Input options and variables
| Option | What it does |
|---|
-n | don't read input; data is created in the filter or read via input/inputs |
-s | collect all input documents into one array |
-R | read lines as text, not JSON (with -s — the whole input as one string) |
-f file | take the filter from a file |
--arg name value | pass a string as $name |
--argjson name JSON | pass a number, array or object as $name |
--slurpfile name file | JSON from a file — as an array in $name |
--rawfile name file | a file's contents as a string in $name |
--args / --jsonargs | remaining arguments — as strings / JSON values in $ARGS.positional |
Environment variables are available as $ENV.NAME or env.NAME.
Paths and selection
| Filter | What it does |
|---|
. | the whole input |
.a.b, .a["b"], ."a-b" | a field; quotes are for names with a hyphen, space or dot |
.[0], .[-1], .[2:4] | element by index, the last one, a slice |
.[] | all array elements (or object values), one by one |
.a?, .[]? | the same, but no error if the type doesn't match |
.. | recursively all values at any depth |
f, g | both results, one after the other |
f | g | the result of f as input to g |
[ f ] | collect all results of f into an array |
{a: f, b} | build an object; {b} = {b: .b}; {(.k): .v} — a computed key |
Operators and constructs
| Construct | What it does |
|---|
+ - * / % | arithmetic; + also concatenates strings, arrays and objects |
== != < <= > >= | comparisons |
and, or, not | logic: select(.a and (.b | not)) |
a // b | b if a is null, false or nothing |
if … then … elif … else … end | condition |
try f catch g | catch an error; f? — silently skip an error |
. as $x | … | save a value into a variable |
reduce .[] as $x (0; . + $x) | fold: accumulate a result over the elements |
def f: …; | your own function |
.a = v, .a |= f, .a += v | assign, update via a filter, add |
del(.a) | delete a field or elements |
"\(.name): \(.age)" | interpolate values into a string |
Built-in functions
| Functions | What they do |
|---|
length, keys, keys_unsorted, has("k"), type | length (of a string, array, object), keys, key presence, type |
select(cond), empty, error("msg") | filtering; "nothing"; an error |
map(f), map_values(f) | apply to each array element / object value |
add, any(cond), all(cond), min, max, min_by(f), max_by(f) | sum/concatenation, at least one / all, minimum, maximum |
sort, sort_by(f), group_by(f), unique, unique_by(f), reverse | sorting, grouping, unique values |
first, last, first(f), limit(n; f), range(n) | first/last values, generating numbers |
flatten, index(x), contains(x), inside(x) | flatten, find a position, check containment |
to_entries, from_entries, with_entries(f) | object ↔ array of {key, value}; rename or filter keys |
paths, path(f), getpath(p), setpath(p; v) | working with paths inside a document |
tostring, tonumber, tojson, fromjson | type conversion, JSON inside a string |
split(s), join(s), ascii_downcase, ascii_upcase | strings |
startswith, endswith, ltrimstr, rtrimstr | prefixes and suffixes |
test(re), match(re), capture(re), sub(re; s), gsub(re; s) | regular expressions (the "i" flag as the second argument — case-insensitive) |
now, todate, fromdate, strftime(fmt) | time: Unix time ↔ ISO 8601 |
input, inputs | the next input document / all remaining ones (together with -n) |
@csv, @tsv, @sh, @base64, @base64d, @uri, @html, @json | format a value as CSV, TSV, shell arguments, Base64… |
Examples
cat > users.json <<'EOF'
{"users":[
{"name":"anna","age":31,"roles":["admin","dev"],"active":true},
{"name":"bob","age":25,"roles":["dev"],"active":false}
]}
EOF
# pretty-print and check that the JSON is valid at the same time
jq . users.json
# names one per line, without quotes
jq -r '.users[].name' users.json
# only active users over 30
jq -r '.users[] | select(.active and .age > 30) | .name' users.json
# who has the admin role
jq -r '.users[] | select(.roles | index("admin")) | .name' users.json
# a new object per user — one line per record
jq -c '.users[] | {name, roles: (.roles | length)}' users.json
# number of records and average age
jq '.users | length' users.json
jq '[.users[].age] | add / length' users.json
# how many users in each group
jq -c '.users | group_by(.active) | map({active: .[0].active, count: length})' users.json
# to TSV for sort, awk, cut
jq -r '.users[] | [.name, .age] | @tsv' users.json
# safely substitute a value from a shell variable
jq --arg n "$USER" '.owner = $n' users.json
# merge several JSON files into an array
jq -s '.' a.json b.json
# lines of text → a JSON array
printf 'one\ntwo\n' | jq -R . | jq -s -c .
# Unix time to a date
echo '{"ts":1700000000}' | jq -r '.ts | todate'
# "edit a file": jq has no -i, write to a temp file and swap it in
jq '.users[1].active = true' users.json > users.tmp && mv users.tmp users.json
Pitfalls
- There's no
-i. jq '…' f.json > f.json empties the file before jq reads it. Write to a temporary file and mv it.
- Without
-r strings stay quoted: "anna". For a shell variable or a loop you usually need -r.
- A nonexistent field is
null, not an error. A typo in a name silently gives null. Add -e to get a non-zero exit code.
// also fires on false. .active // true turns a real false into true. For boolean fields check explicitly: if .active == null then true else .active end.
- A field with a hyphen: jq reads
.a-b as ".a minus b". Write ."a-b" or .["a-b"].
| binds weaker than a comma. .a | length, .b means .a | (length, .b), and .b is looked up inside .a. Use parentheses: (.a | length), .b.
- Don't splice shell values into the filter.
jq ".name == \"$x\"" breaks on quotes in $x. Pass data via --arg / --argjson.
--arg always gives a string. With --arg n 5, the comparison .age > $n compares a number with a string. For numbers use --argjson.
.users[] produces several separate values, not an array. To get an array again, wrap it in [ … ] or use map.
- A parse error (
parse error: Invalid numeric literal) means the input wasn't JSON: an HTML error page, an empty response, extra text. Check the input without jq.
See also
yq · curl · xmllint · sort · awk