Topolearn

Learn jq

Command-line JSON processor: query, filter and reshape JSON

14 lessons · 2 hours · 4 levels · covers jq 1.8

jq is a small, fast command-line program and language for slicing, filtering, transforming and generating JSON. It is the standard way to read API responses, cloud CLI output and JSON logs in shell scripts and pipelines.

Sign in free to track progressOfficial docs ↗

Before you start

jq builds on these; the tree links to the exact lessons you need.

BashEssentials level

How deep do you want to go?

1. EssentialsRead and write simple code, do the everyday basics4 lessons · 34 min in total
2. PracticalUse it productively at work, with the usual idioms8 lessons · 1 hour in total
3. AdvancedThe less common features, performance and trade-offs11 lessons · 2 hours in total
4. ExpertInternals and the edge cases experts know14 lessons · 2 hours in total

The jq tree

jqPretty-printing and field accessPretty-printing andfield accessArrays: index, slice and iterateArrays: index, sliceand iteratePipes, commas and building JSONPipes, commas andbuilding JSONFiltering with select and mapFiltering with selectand mapCommand-line options and passing variablesCommand-lineoptions and passin…Strings, regex and output formatsStrings, regex andoutput formatsWorking with objects: keys, entries, mergeWorking withobjects: keys, entri…Sorting, grouping and aggregatingSorting, grouping andaggregating
Essentials and Practical shown (8 of 14 lessons); the full list is below. Click a lesson to read it.

All 14 lessons, in order

Filter basics

  1. Pretty-printing and field access · Essentials · 6 min

    jq '.' pretty-prints JSON, .name extracts a field, .a.b goes deeper and -r prints strings without quotes.

  2. Arrays: index, slice and iterate · Essentials · 8 min

    Index arrays with .[0], slice with .[2:4], and iterate every element with .[] to get a stream of outputs.

  3. Pipes, commas and building JSON · Essentials · 10 min

    Chain filters with |, produce several outputs with a comma, and build new objects and arrays with {} and [].

Transforming data

  1. Filtering with select and map · Essentials · 10 min

    Keep only matching items with select(condition), transform every element with map(f), and compare with ==, <, and, or, not.

  2. Strings, regex and output formats · Practical · 10 min

    Interpolate with "\(.x)", split, join and test with regexes, and emit CSV, TSV or shell-safe text with @csv, @tsv and @sh.

  3. Working with objects: keys, entries, merge · Practical · 10 min

    Inspect keys, rename and filter keys with with_entries, delete fields with del and merge objects with + and *.

  4. Sorting, grouping and aggregating · Practical · 10 min

    Summarise arrays with sort_by, group_by, unique_by, min_by, max_by, add and length.

jq in scripts

  1. Command-line options and passing variables · Practical · 10 min

    Use -r, -c, -n, -s and -e, and pass shell values safely into a filter with --arg, --argjson and $ENV.

Logic, reduce and functions

  1. Conditionals, defaults and error handling · Advanced · 10 min

    Branch with if-then-elif-else-end, supply defaults with //, and handle bad input with try, catch and the ? operator.

  2. Variables, reduce and defining functions · Advanced · 12 min

    Bind values with as $x, fold a stream with reduce, and define your own reusable functions with def.

  3. Updating JSON: |=, +=, del and in-place edits · Advanced · 10 min

    Modify parts of a document while keeping the rest with update-assignment |=, arithmetic updates like +=, and plain = for setting values.

Advanced jq

  1. Recursion and paths: .., paths, walk · Expert · 12 min

    Search entire documents with .. and paths, read and write by path with getpath/setpath, and transform every node with walk.

  2. Large inputs: inputs, --stream and limits · Expert · 12 min

    Process huge files and endless streams with -n and inputs, the --stream event format, and early-exit helpers like first and limit.

  3. Generators, backtracking and empty · Expert · 12 min

    jq expressions are generators that can produce zero, one or many outputs; understanding this explains cartesian products, empty and label/break.