← All cheatsheets

Data

JSON & jq — query, filter, transform, and build JSON

Query, filter, reshape, and build JSON on the command line with jq: path selectors, pipes, select/map/has, object and array construction, group_by/unique/sort_by, reduce, string ops, raw output, --arg injection, from_entries/to_entries, and slurp/stream for large files.

Docs-checkedjsonjqquerytransformpipeline

Quick reference — reach for these first

Pretty-print / validatejq '.' file.jsonParse, reformat, and color JSON; exits non-zero on invalid input, so it doubles as a validator.
Iterate an arrayjq '.items[]' file.jsonStream each element of the .items array as a separate value for the rest of the pipe.
Transform each elementjq 'map(.x)' file.jsonApply a filter to every element of an input array and collect the results back into an array.
Raw string outputjq -r '.name' file.jsonEmit string values without surrounding quotes or escaping — needed when piping to other shell tools.
Filter by conditionjq 'select(.ok)' file.jsonKeep only inputs where the boolean expression is truthy; drop everything else from the stream.

A jq filter is a pipeline: data flows left to right through stages joined by |

jq filter pipelineFive stages joined by the pipe operator: input JSON, iterate items, filter with select, build an array, format as CSV, producing a CSV report.{ items:[…] }input JSON.items[]iterateselect(.status!= "ok")filter[.id,.name,.status]build array@csvformat||||output → id,name,status / 2,"db","fail" / 3,"cache","degraded"

Text equivalent: Left-to-right pipeline of five boxes. Stage 1 input JSON object with an items array. Arrow to stage 2 .items[] which iterates the array. Arrow to stage 3 select(.status != "ok") which filters the stream. Arrow to stage 4 [.id, .name, .status] which builds a flat array per item. Arrow to stage 5 @csv which formats each array into a CSV row. Output below is a three-line CSV report.

Common tasks

Select & filter · Build & reshape · I/O & arguments

Select & filterBuild & reshapeI/O & arguments
Pretty-print and validate a filejq '.' data.jsonReformatted JSON prints and exit code is 0; a parse error prints to stderr and exits non-zero.
Reach into nested keysjq '.a.b.c' data.jsonPrints the value at that path, or null if any segment is missing.
Iterate an array of objectsjq '.items[]' data.jsonEach object prints on its own as a separate top-level value.
Iterate safely when the field may be absentjq '.items[]?' data.jsonNo 'Cannot iterate' error when .items is null or missing — it yields nothing instead.
Filter a stream by a predicatejq '.items[] | select(.status == "fail")','data.jsonOnly elements whose status equals fail survive the pipe.
Map and pick fields into new objectsjq '[.items[] | {id, label: .name}]' data.jsonReturns an array of trimmed objects; {id} is shorthand for id: .id.
Keep objects that have a keyjq '[.items[] | select(has("error"))]' data.jsonOnly objects containing an error key are returned.
Group, dedupe, and sortjq 'group_by(.status) | map({status: .[0].status, n: length})' data.jsonOne row per distinct status with its count; use unique and sort_by(.x) for related shaping.
Sum or fold with reducejq 'reduce .items[].latency_ms as $x (0; . + $x)' data.jsonPrints the running total; the accumulator starts at 0 and updates per element.
Inject shell values safelyjq --arg s fail '.items[] | select(.status == $s)' data.json$s is a quoted string; use --argjson n 5 to pass a number/JSON literal instead.
Convert object <-> entriesjq 'to_entries | map(select(.value > 0)) | from_entries' data.jsonRound-trips an object through {key,value} pairs so you can filter by value.
Slurp multiple inputs into one arrayjq -s '.' a.json b.jsonAll inputs are read into a single array before the filter runs (-s / --slurp).
Extract text from a Claude API responsejq -r '.content[0].text' response.jsonPrints just the assistant text from a Messages API reply (Opus 4.x / Sonnet) without JSON quoting.
Stream a file too big for memoryjq --stream -c '. ' huge.jsonEmits [path, leaf-value] events incrementally instead of loading the whole document.

Turn an API response into a failing-checks CSV report

csv-report

1
Fetch a raw JSON response (here saved as the input we will shape).
curl -s https://API_HOST/v1/healthchecks
# {"items":[{"id":1,"name":"api","status":"ok","latency_ms":42},{"id":2,"name":"db","status":"fail","latency_ms":1200},{"id":3,"name":"cache","status":"degraded","latency_ms":300}]}
2
Iterate the array so each check becomes a value in the pipe.
curl -s https://API_HOST/v1/healthchecks | jq '.items[]'
# {"id":1,"name":"api","status":"ok","latency_ms":42}
# {"id":2,"name":"db","status":"fail","latency_ms":1200}
# {"id":3,"name":"cache","status":"degraded","latency_ms":300}
3
Keep only the checks that are not ok.
... | jq '.items[] | select(.status != "ok")'
# {"id":2,"name":"db","status":"fail","latency_ms":1200}
# {"id":3,"name":"cache","status":"degraded","latency_ms":300}
4
Prepend a header row and reshape each survivor into a flat array of fields.
... | jq -r '["id","name","status","latency_ms"], (.items[] | select(.status != "ok") | [.id, .name, .status, .latency_ms])'
# ["id","name","status","latency_ms"]  (header, then one array per failing row)
5
Format every array as CSV and verify the result parses as a 3-line report. EVALUATE: expect exactly 1 header + 2 data rows, numbers unquoted, strings quoted.
... | jq -r '["id","name","status","latency_ms"], (.items[] | select(.status != "ok") | [.id, .name, .status, .latency_ms]) | @csv'
# id,name,status,latency_ms
# 2,"db","fail",1200
# 3,"cache","degraded",300

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
jq: error: Cannot index array with "name"Check whether the value at that point is an array; print the parent with 'jq '.items''.You applied an object accessor like .name directly to an array value.Insert .[] to iterate first: '.items[] | .name' instead of '.items.name'.
Output is just 'null'Print the parent level and compare key names exactly, including case: 'jq 'keys''.The path points at a key that does not exist, so jq returns null rather than erroring.Fix the path to the real key name, or use '?' / '// "default"' to handle absence.
Shell complains about ! $ ( ) or splits the programConfirm the whole jq program is wrapped in single quotes.The shell is expanding the unquoted filter before jq sees it.Single-quote the program; pass dynamic values with --arg / --argjson, not string interpolation.
Strings come out wrapped in double quotesLook at whether you need a raw value for a downstream shell command.jq emits JSON-encoded strings by default, with quotes and escapes.Add -r (--raw-output) to print the bare string contents.
@csv / @tsv errors with 'Cannot be csv-formatted'Check the value immediately before @csv is an array.@csv formats an array of scalars into one row; it rejects objects or bare scalars.Wrap the fields in brackets first: '[.id, .name, .status] | @csv'.
jq hangs or eats all memory on a huge fileCheck the file size and whether you really need the whole document in memory.Default mode parses the entire input before filtering.Use --stream for incremental parsing, or -c with per-line NDJSON input.
Program with newlines fails from the command lineCheck whether the filter was quoted across lines or lost its pipes.Long multi-line programs are awkward to pass inline.Move the program into a file and run 'jq -f program.jq data.json'.

References

jq 1.7+ on a POSIX shell; examples single-quote the program so the shell does not expand it. API_HOST and other CAPS tokens are placeholders. @csv quotes strings and leaves numbers unquoted. The Claude example assumes a Messages API response whose top-level content is an array of blocks.

Related sheets