What is the jq identity filter?

The identity filter is a single dot (.) and returns its input unchanged. It is the simplest filter and the starting point of most pipelines — for example, .name reads the name field of the input, where the leading dot is the identity that the field access applies to.

What is the difference between map and select in jq?

map(f) applies the filter f to every element of an array and collects the results into a new array, transforming each item. select(cond) is a filter that outputs its input only if the condition is true, otherwise nothing — it is used to keep or drop items, often inside map, as in map(select(.age > 18)).

How does the pipe operator work in jq?

The pipe | feeds the output of the filter on its left as the input to the filter on its right, like a Unix shell pipe. So .users | length first selects the users array, then counts it. Pipelines can be as long as needed, each stage transforming the stream.

What does the comma operator do in jq?

The comma runs several filters on the same input and concatenates all their outputs into one stream. For example, .a, .b emits the value of a followed by the value of b. It is how you produce multiple results from a single input.

How do I iterate over an array in jq?

The array/object value iterator .[] produces each element of an array (or each value of an object) as a separate output in the stream. Combine it with select to filter, as in .[] | select(.active), or wrap a pipeline in [ ... ] to collect the results back into an array.

jq Filter Reference — Gera Tools

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

jq is a command-line processor for JSON: you pipe JSON in, apply a filter, and get transformed JSON out. A jq program is a filter — a small expression that takes an input value and produces zero or more output values. Filters compose with the pipe | and the comma ,. This reference lists the operators, constructors and the built-in functions you use most.

How it works

jq reads a stream of JSON values and runs your filter against each one. The most basic filter is . (identity), which returns the input untouched. From there you navigate with .field, .[index] and the iterator .[], transform with map, select, arithmetic and string functions, and assemble results with {} / [] constructors. The pipe | connects stages so each filter’s output becomes the next one’s input.

Worked examples

echo '{"users":[{"name":"A","age":30},{"name":"B","age":15}]}' \
  | jq '.users | map(select(.age >= 18)) | map(.name)'
# => ["A"]

echo '{"a":1,"b":2}' | jq 'to_entries | map(.key)'
# => ["a","b"]

echo '[1,2,3]' | jq 'add'
# => 6

Notes and tips

Wrap an iterating pipeline in [ ... ] to collect a stream back into an array, and use -r on the command line for raw (unquoted) string output. select emits nothing when its condition is false, so it naturally filters streams. Prefer reduce or add for aggregation, and to_entries / from_entries to treat an object as an iterable list of key/value pairs.