The jq filters used day to day, grouped by job: reach into a value, filter and select, work the collections, transform values and strings, reshape into a new object or array, update paths in place, branch on logic, and handle advanced reduction, plus the command-line flags that shape input and output. Each row pairs the filter with the result it produces.
jq is a filter: it reads JSON on stdin, runs a pipeline of expressions separated by pipes, and writes JSON on stdout. The dot is the current value; everything builds on it. The fastest way to learn is to pipe real data through the recipes below and watch the output. Run them as jq 'filter' file.json or curl ... | jq 'filter'.
Reference table · 65 entries
jq RecipesExplained
65 of 65 rows
Access
The whole input, pretty-printed.
The value at a key, or nested keys.
The value at a key whose name has special characters.
The first element of an array (negative counts from the end).
Each element of an array, or each value of an object, on its own line.
The value at key, or null, without an error when the key is missing.
Filter & select
The input unchanged when cond is true, otherwise nothing.
Apply expr to every element of an array and collect the results.
The sorted key names, or the values, of an object as an array.
The length of an array or string, or the count of keys in an object.
Only the elements whose age is greater than 18, as one array.
Collections
True when at least one, or when every, element is truthy or passes a filter.
True when the key k exists in the object; in runs the same test from the key's side.
The first element, the last, or only the first n outputs of f.
The smallest, or largest, value in an array.
The numbers from 0 up to n, each as its own output.
Nested arrays collapsed into a single flat array.
True when x occurs somewhere within the input; inside flips the roles.
Apply f to every value from the bottom up, then rebuild the whole input.
Transform
An array of just the price field from each element.
The sum of an array of numbers, or the merge of an array of objects.
Coerce a value to a string, or a numeric string to a number.
Encode the input as a JSON string or base64.
A string lowercased.
Strings
A string with the value of expr spliced into the text.
Replace every match of the pattern, or only the first, with s.
Break a string into an array on a separator, or glue an array into one string.
Test a string against a pattern, or pull out the matches and named captures.
Strip a prefix, or a suffix, only when it is present.
True or false: the string starts, or ends, with s.
A string uppercased.
An array encoded as a CSV row, a TSV row, or quoted shell arguments.
Reshape
A new object with only the id and name fields of the input.
An array of every item's name.
An array of {key, value} objects from an object.
An object built from an array of {key, value} objects.
Elements grouped into subarrays by their cat field.
Sort by a field, or keep one element per distinct id.
Update & paths
Update the value at key by running f on it.
Overwrite the value at key with v.
Add n to the value at count, in place.
Read, write, or delete values at paths given as arrays.
Control & logic
a when c is true, b otherwise, with elif for more branches.
Run f, and run g with the error message instead when f fails.
Stop with an error carrying msg, unless a try catches it.
No output at all; that branch simply vanishes from the results.
Combine true and false values, or flip one.
Advanced
Fold the whole array into one running total.
Like reduce, but it emits the state after every step, not just the last.
The next input, or every remaining input, pulled in mid-filter.
A value as its JSON text, or JSON text parsed back into a value.
Base64 text decoded back into the original string.
Assignment deep in the structure, creating missing levels along the way.
a if it is not null or false, otherwise b (a default value).
The input with one key removed.
Every path in the input as an array of keys, top to bottom.
Variables & CLI
Define $name as a shell string, usable inside the filter.
Define $name from raw JSON, for numbers, booleans, arrays, or objects.
Define $name as the whole contents of a JSON file.
Print string results raw, without quotes or escapes.
Print each result compact on one line, with no indentation.
Run the filter once on null, to build output from nothing.
Read all of the input into one array before the filter runs.
Set the exit code from the last output, so shell scripts can test the result.
The value of an environment variable, read inside the filter.