jq Cheat Sheet: select, map, group_by, @csv and More, With Examples

November 2, 2026 · 6 min read

jq is a command-line processor for JSON: jq '<filter>' file.json reads the file, applies the filter and prints the result. The essentials are .key to read a field, .[] to iterate an array, | to chain steps, select(cond) to filter and map(f) to transform every element; add -r for raw text output.

Every example below runs against the same small file, and the output shown is what jq 1.7 prints. You can try them without installing anything: the query bar in our online JSON formatter runs jq filters locally in your browser. If you only need to pick values out of a document rather than reshape it, a JSONPath expression tester may be simpler; jq vs JSONPath explains when each fits.

Sample input: users.json

[
  { "name": "Ada",   "age": 36, "team": "core",  "email": "ada@example.com" },
  { "name": "Linus", "age": 28, "team": "infra", "email": null },
  { "name": "Grace", "age": 45, "team": "core" }
]

Basic filters

.[] produces a stream of separate values, not an array. Wrap it in brackets, [.[].name], to collect the stream back into one array.

Output flags: -r, -c, -s, -n

-s is the bridge between line-delimited files and normal jq: it turns many values into one array so map, group_by and sort_by work on them. More on that format in what NDJSON is and how to process it.

select: filter by condition

$ jq -r '.[] | select(.age > 30) | .name' users.json
Ada
Grace

$ jq -c '.[] | select(.team == "core" and .age < 40)' users.json
{"name":"Ada","age":36,"team":"core","email":"ada@example.com"}

$ jq -r '.[] | select(.name | startswith("G")) | .name' users.json
Grace

$ jq -r '.[] | select(.name | test("^l"; "i")) | .name' users.json
Linus

select(cond) passes its input through when the condition is truthy and outputs nothing otherwise. Only false and null are falsy, so select(.email) keeps Ada only: Linus's null and Grace's missing key both drop out. To keep an array instead of a stream, use map(select(...)):

$ jq -c 'map(select(.team == "core")) | map(.name)' users.json
["Ada","Grace"]

$ jq 'map(select(.team == "core")) | length' users.json
2

map and building new objects

$ jq -c 'map(.name)' users.json
["Ada","Linus","Grace"]

$ jq -c 'map({name, age})' users.json
[{"name":"Ada","age":36},{"name":"Linus","age":28},{"name":"Grace","age":45}]

$ jq -c 'map({user: .name, senior: (.age >= 40)})' users.json
[{"user":"Ada","senior":false},{"user":"Linus","senior":false},{"user":"Grace","senior":true}]

$ jq 'map(.age) | add' users.json
109

$ jq 'map(.age) | add / length' users.json
36.333333333333336

{name, age} is shorthand for {name: .name, age: .age}. Wrap any computed value in parentheses. map(f) is exactly [.[] | f].

keys, has, del and to_entries

to_entries, from_entries and with_entries(f) are how you filter or rename keys when you do not know them in advance. with_entries(f) is shorthand for to_entries | map(f) | from_entries.

sort_by, group_by, unique_by

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

$ jq -c 'sort_by(.age) | reverse | map(.name)' users.json
["Grace","Ada","Linus"]

$ jq -c 'group_by(.team) | map({team: .[0].team, count: length})' users.json
[{"team":"core","count":2},{"team":"infra","count":1}]

$ jq -c 'map(.team) | unique' users.json
["core","infra"]

$ jq -c 'max_by(.age) | .name' users.json
"Grace"

group_by(f) returns an array of arrays, sorted by the grouping value; the map({team: .[0].team, count: length}) step turns each group into a summary row. Sort by several fields with sort_by(.team, .age).

@csv and @tsv: JSON to spreadsheet rows

$ jq -r '.[] | [.name, .age, .email] | @csv' users.json
"Ada",36,"ada@example.com"
"Linus",28,
"Grace",45,

$ jq -r '["name","age"], (.[] | [.name, .age]) | @tsv' users.json
name	age
Ada	36
Linus	28
Grace	45

@csv and @tsv take an array per row, so build the row first with [...]. Always add -r, or every line is wrapped in an extra JSON string with escaped quotes. Null becomes an empty cell. Both fail on nested objects or arrays inside a row; flatten them first, or use a JSON to CSV converter that flattens nested keys into columns for you.

Variables: --arg and --argjson

$ jq -r --arg team core '.[] | select(.team == $team) | .name' users.json
Ada
Grace

$ jq -r --argjson min 30 '.[] | select(.age > $min) | .name' users.json
Ada
Grace

$ jq -r '.[] | .name as $n | "\($n) is \(.age)"' users.json
Ada is 36
Linus is 28
Grace is 45

--arg always passes a string; comparing .age > $min with a string would be wrong, which is why numbers go through --argjson. Passing shell values this way is safer than pasting $VAR into the filter, which breaks on quotes. \(expr) interpolates inside a string.

Null-safe access and defaults

// treats false as missing too: false // true is true. If a field can legitimately be false, test with if .x == null then ... else .x end instead.

Editing values in place

$ jq -c 'map(.age += 1) | map(.age)' users.json
[37,29,46]

$ jq -c '.[1].email = "linus@example.com" | .[1]' users.json
{"name":"Linus","age":28,"team":"infra","email":"linus@example.com"}

$ jq -c 'map(.name |= ascii_downcase) | map(.name)' users.json
["ada","linus","grace"]

jq never edits the file itself. Write to a temporary file and move it: jq '...' in.json > tmp.json && mv tmp.json in.json. Redirecting straight back to in.json empties it before jq reads it.

Recursive search

.. walks every value at every depth. jq '[.. | .email? // empty]' collects every email anywhere in a document, and jq 'paths(type == "number")' lists the path to every number. For the equivalent selection syntax in apps and API tests, the JSONPath cheat sheet covers $..email and friends.