Getting started

Introduction

jq filters JSON on the command line: pick fields, reshape objects, and reformat output. This sheet covers the filters and flags used most often.

The input

{
  "account": { "plan": "pro", "seats": 3 },
  "users": [
    { "name": "Ada", "role": "admin", "active": true },
    { "name": "Linus", "role": "dev", "active": false },
    { "name": "Grace", "role": "dev", "active": true }
  ]
}

Examples read this file as api.json.

See: Invoking jq

Field access

jq '.users[0].name' api.json
# → "Ada"

. is the input document; .foo reads a key. Strings keep their quotes unless -r is passed.

See: Object identifier-index

Raw and compact output

jq -c '.users[1]' api.json
# → {"name":"Linus","role":"dev","active":false}

Flags

FlagEffect
-rraw strings, no quotes
-cone line per value
-Ssort keys
--tabindent with tabs
--indent 4indent with 4 spaces
-eexit 1 on false/null, 4 if empty

See: Invoking jq

Selecting

Nested fields

jq -r '.account.plan' api.json
# → pro

Chain keys to walk deeper. A missing key yields null, not an error.

See: Object identifier-index

Arrays and slices

jq -c '.users[0:2] | map(.name)' api.json
# → ["Ada","Linus"]

.[0] is the first element and .[-1] the last; .[2:] runs to the end.

See: Array/string slice

Iteration

jq -r '.users[].name' api.json
# → Ada
# → Linus
# → Grace

.[] streams each element. Wrap the filter in brackets to collect the stream back into an array: [.users[].name].

See: Array/object value iterator

Optional access

jq '.users[] | .tags[]?' api.json
# → no output

? suppresses the error, so a missing tags key yields nothing instead of aborting the run.

See: Optional operator

Filtering

select

jq -r '.users[] | select(.active).name' api.json
# → Ada
# → Grace

select(f) passes the input through only when f is true. Swap in any test, such as select(.role == "dev").

See: select

map

jq -c '.users | map(.name)' api.json
# → ["Ada","Linus","Grace"]

map(f) applies f to every element and returns an array.

See: map

map_values

echo '{"ada":2,"linus":5}' | jq -c 'map_values(. + 1)'
# → {"ada":3,"linus":6}

On objects map_values keeps the keys; on arrays it behaves like map.

See: map_values

Keys and counts

jq -c '.users | length, (.[0] | keys)' api.json
# → 3
# → ["active","name","role"]

has("users") tests for one key. length also counts characters in a string and keys in an object.

See: keys

Totals

echo '[12,48,7]' | jq -c '[add, min, max]'
# → [67,7,48]

add sums an array; min and max read the same array.

See: add

Sorting and grouping

sort_by

jq -c '.users | sort_by(.name) | map(.name)' api.json
# → ["Ada","Grace","Linus"]

Plain sort compares whole values; sort_by(.key) sorts objects by one field.

See: sort_by

group_by

jq -c '.users|group_by(.role)|map([.[0].role,length])' api.json
# → [["admin",1],["dev",2]]

Groups are sorted by key. Each group is an array, so length counts its members.

See: group_by

unique

jq -c '[.users[].role] | unique' api.json
# → ["admin","dev"]

unique_by(.key) dedupes objects by one field instead of the whole value.

See: unique

Building values

Objects and arrays

jq -c '.users[0] | {name, active}' api.json
# → {"name":"Ada","active":true}

{name} is shorthand for {name: .name}. [...] collects a stream into an array.

See: Object construction

String interpolation

jq -r '.users[] | "\(.name) is \(.role)"' api.json
# → Ada is admin
# → Linus is dev
# → Grace is dev

\(...) interpolates any filter into a string; pair it with -r to drop the quotes.

See: String interpolation

Conditionals

jq -r '.users[] | if .active then "in" else "out" end' api.json
# → in
# → out
# → in

Add elif .role == "admin" between if and else for more branches. end is required.

See: if-then-else

Alternatives

echo '{"nick":null,"name":"Ada"}' | jq -r '.nick // .name'
# → Ada

// yields the right side when the left is false or null.

See: Alternative operator

Errors

jq -r '.users[0] | try (.name - 1) catch .' api.json
# → string ("Ada") and number (1) cannot be subtracted

catch . receives the message. ? is shorthand for try.

See: try-catch

Transforming

Entries

echo '{"ada":2,"linus":5}' | jq -c 'to_entries'
# → [{"key":"ada","value":2},{"key":"linus","value":5}]

with_entries

echo '{"ada":2,"linus":5}' | jq -c 'with_entries(.value += 1)'
# → {"ada":3,"linus":6}

with_entries(f) is to_entries | map(f) | from_entries.

See: to_entries

reduce

echo '[12,48,7]' | jq 'reduce .[] as $n (0; . + $n)'
# → 67

(0; . + $n) seeds the accumulator at 0 and adds each element.

See: reduce

Arguments

jq -n -c --arg name Ada --argjson n 2 '{name: $name, n: $n}'
# → {"name":"Ada","n":2}

--arg always makes a string, --argjson parses JSON. --slurpfile v f.json reads a file into $v; --rawfile v f.txt reads plain text.

See: Invoking jq

Output formats

CSV and TSV

CSV

jq -r '.users[] | [.name,.role] | @csv' api.json
# → "Ada","admin"
# → "Linus","dev"
# → "Grace","dev"

TSV

jq -r '.users[] | [.name,.role] | @tsv' api.json
# → Ada	admin
# → Linus	dev
# → Grace	dev

@csv quotes strings and separates fields with commas; @tsv uses tabs.

See: Format strings

JSON and Base64

JSON text

jq -r '.users[0] | @json' api.json
# → {"name":"Ada","role":"admin","active":true}

Base64

jq -r '.users[0].name | @base64' api.json
# → QWRh

@base64d decodes, and @text stringifies any value.

See: Format strings

Generating JSON

jq -n -c --arg user Ada '{user: $user, admin: false}'
# → {"user":"Ada","admin":false}

-n runs the filter once with no input, so args and constants build the document. Use inputs to read stdin from inside the program.

See: Invoking jq

Files and streams

Multiple files

# a.json = {"a":1}
# b.json = {"b":2}
jq -cs 'add' a.json b.json
# → {"a":1,"b":2}

Without -s, each value in each file is processed on its own.

See: Invoking jq

JSON Lines

# events.jsonl = {"user":"ada","ms":12}
#               {"user":"linus","ms":48}
jq -c '.ms' events.jsonl
# → 12
# → 48

Slurping

jq -cs 'map(.ms) | add' events.jsonl
# → 60

JSON Lines files parse as one value per line; -s collects them into one array.

See: Invoking jq

Streaming

echo '{"a":[{"b":1}]}' | jq -c --stream 'select(length == 2)'
# → [["a",0,"b"],1]

--stream emits [path, leaf] pairs as the input parses, keeping memory flat on large files.

See: Streaming

0 Comments for this cheatsheet. Write yours!