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.

What is the jq Filter Reference?

Searchable jq reference covering identity, field and index access, pipes, the comma, object/array construction, conditionals, reduce, and the most-used built-in functions like map, select, keys, length and to_entries. It runs free in your browser on Gera Tools, with nothing uploaded.

jq Filter Reference — Gera Tools

Name: jq Filter Reference
Creator: Gera Tools
License: https://creativecommons.org/licenses/by/4.0/

Get one useful tool a week

Like this tool? Enter your email and we'll send you one genuinely useful Gera tool a week — plus a link to come back to this one. No spam, one-click 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.

Core concepts

jq processes a stream of JSON values. The filter you write runs once per input value and can produce zero, one, or many output values. Everything in jq is a filter, including field access and arithmetic — which is why they all compose with | the same way.

Navigation:

.                   # identity — return input unchanged
.field              # field access
.["field"]          # same, for keys with special chars
.[0]                # array index
.[-1]               # last element
.[2:5]              # array slice
.[]                 # iterate: emit each element as a separate value
..                  # recursive descent

Transformation:

map(f)              # apply f to each array element, collect results
map(select(cond))   # filter array to matching elements
reduce .[] as $x (0; . + $x)   # fold/reduce

Construction:

{name: .name, age: .age}   # object construction
[.a, .b, .c]               # array construction
[ .[] | select(.active) ]  # collect filtered stream into array

Aggregation and introspection:

length              # array/object length, string character count
keys                # object keys as sorted array
values              # object values as array
has("field")        # boolean key presence test
to_entries          # [{key:"k", value:v}, ...] — iterate object as pairs
from_entries        # inverse of to_entries
add                 # sum array / concatenate strings / merge objects
unique              # unique values in sorted array
group_by(.field)    # partition array into sub-arrays by key
sort_by(.field)     # sort array by key

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 stage’s input.

Worked examples

Filter an array by condition and extract a field:

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

Iterate object keys:

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

Sum an array:

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

Reshape an object:

echo '{"first":"Jane","last":"Doe","age":32}' \
  | jq '{fullName: (.first + " " + .last), age}'
# => {"fullName":"Jane Doe","age":32}

Command-line flags to know

Flag	Effect
`-r`	Raw output — strings without JSON quotes
`-c`	Compact output — one JSON value per line
`-n`	Null input — useful when building from scratch with `input`/`inputs`
`--arg name val`	Bind a shell variable as a jq string variable `$name`
`--argjson name val`	Bind a JSON-typed variable

Wrap an iterating pipeline in [ ... ] to collect a stream back into an array. select emits nothing when its condition is false, so it naturally filters without needing an explicit removal step.