Learn jq

A filter language: a program is a pipeline that streams JSON values through small filters.

Getting started

Identity & fields A jq program is a filter: it takes the input document and produces zero or more outputs. . is the simplest…
Nesting & missing keys Chain fields to walk into nested objects. Asking for a key that doesn't exist is not an error — you get…
Array index & slice Index arrays with [n] (zero-based; negative numbers count from the end) and slice them with [from:to] (the…
Iterate & collect .[] turns an array into a stream of its elements — one output each. Wrap any filter in [ … ] to collect a…

Pipes | feeds each output of the filter on its left into the filter on its right. It is how small filters combine…
Building objects { … } builds a new object. {name} is shorthand for {name: .name}, and a value can be any expression — wrap…
Strings & interpolation "…\(expr)…" inserts the result of any filter into a string. Combine it with join, ascii_downcase, sub and…

select & comparisons select(condition) lets a value through only when the condition is true — it is jq's way to filter.
and / or / not Combine conditions with and and or, and invert one with not.
if / elif / else if … then … elif … else … end picks one branch per input. Every condition and branch is itself a filter.
Testing text & arrays test, startswith, endswith and contains return booleans, so they slot straight into select.
Missing values: // and empty a // b gives a unless it is null, false or produces nothing — then it gives b. empty produces no output at…

map & select together map(f) runs f on every element and collects the results into a new array. Combine it with select to filter…
Updating values Assignment operators produce a modified copy of the input: = sets a value, |= updates it from its old value,…
Working with objects keys lists the key names, has(k) tests for one, a + b merges two objects (the right side wins), and…
Types & conversion type names a value's type, and tostring, tonumber, tojson and fromjson convert between types.

Counting & math Arrays have length, add, min and max, and the usual arithmetic works: + - * / %.
Sort, group & unique sort_by(key) orders an array, group_by(key) buckets its elements into arrays, and unique drops duplicates.…
reduce & foreach reduce stream as $x (start; update) folds a stream into a single value. foreach is the same, but emits the…
limit, first & range limit(n; stream) and first(stream) stop as soon as they have enough, instead of computing everything. range…

CSV & TSV @csv and @tsv write an array as one row of text. Build the row with [ … ], one row per result. When the last…
Records to a table Most data is an array of objects. List the columns once, in a variable, and use that one list for the header…
Quoting & escaping Values with commas, quotes or line breaks need care. @csv puts every string in double quotes and doubles any…
IN IN(…) asks whether its input is one of several values and answers true or false, so it belongs inside…
INDEX & JOIN INDEX(f) turns an array into an object keyed by what f gives for each element: a lookup table. INDEX(source;…

Variables expr as $name | … binds a value for the rest of the pipeline — handy when you need it twice. A pattern on…
Your own functions def name(params): body; defines a reusable filter. A parameter written $n receives a value; a plain name…
Recursion: .., paths, walk .. visits every value in the document, at any depth. Pair it with a type filter such as numbers or strings.…

tostream tostream flattens any value into events: [path, value] for every leaf, and a one-element [path] event that…
fromstream & truncate_stream fromstream(events) builds values back from events: it gives one value each time an event closes a top-level…

try, catch & ? Some filters fail on some inputs — tonumber on "two", for instance. try f catch g recovers with a fallback,…

jq here vs jq 1.7 jsonquery runs jq programs with jaq, a Rust re-implementation of jq. Everyday filters behave the same, but a…