jq (JSON Processor) Cheat Sheet
A reference for jq's filter syntax to query, transform, and reshape JSON data directly from the command line.
1 PageIntermediateFeb 15, 2026
Basic Filters
Selecting and extracting fields from JSON.
bash
echo '{"name":"Alice","age":30}' | jq '.' # pretty-printcat data.json | jq '.name' # get field "name"cat data.json | jq '.address.city' # nested fieldcat data.json | jq '.users[0]' # first array itemcat data.json | jq '.users[]' # iterate all itemscat data.json | jq -r '.name' # raw string, no quotes
Filtering & Mapping
Selecting subsets and transforming array elements.
bash
cat data.json | jq '.users[] | select(.age > 18)' # filter itemscat data.json | jq '[.users[].name]' # array of namescat data.json | jq '.users | map(.name)' # same, using mapcat data.json | jq '.users | length' # count itemscat data.json | jq '.users | sort_by(.age)' # sort by fieldcat data.json | jq '.users[] | {name, age}' # reshape object
Building Output
Constructing new JSON structures and CSV output.
bash
cat data.json | jq '{fullName: .name, isAdult: (.age >= 18)}'cat data.json | jq '.users | map({id, label: .name})'cat data.json | jq -r '.users[] | [.name, .age] | @csv'cat data.json | jq '.a // "default"' # fallback if a is null/missingcat data.json | jq 'del(.password)' # remove a key
Key Operators & Functions
Common jq building blocks.
- .- Identity filter; represents the current input
- .[]- Iterates over array elements or object values
- select(cond)- Keeps only values where the condition is true
- map(f)- Applies filter f to each element and collects results into an array
- |- Pipes output of one filter into the next
- ?- Suppresses errors, e.g. `.foo?` skips items missing that key
- @csv / @tsv- Formats an array as a CSV or TSV row
Pro Tip
Use `jq -c` (compact output) when piping results into another line-oriented tool, and `jq -e` in scripts so jq exits with a non-zero status when the filter produces null or false — handy for shell error checking.
Was this cheat sheet helpful?
Explore Topics
#JqJSONProcessor#JqJSONProcessorCheatSheet#ToolsOthers#Intermediate#BasicFilters#FilteringMapping#BuildingOutput#KeyOperatorsFunctions#Databases#CommandLine#CheatSheet#SkillVeris
