The jq Cheat Sheet: 25 Filters You'll Actually Use

Most jq cheat sheets list syntax you'll never touch. This one runs on a single realistic document — an order with a customer, three line items, and shipping — and shows what each filter actually returns. Every output below was produced by jq 1.8.2 on this exact data, and you can reproduce any of them in the playground two clicks from now.

The example document

{
  "order": {
    "id": 4172,
    "customer": { "name": "Dana Reyes", "tier": "gold",
                  "emails": ["[email protected]", "[email protected]"] },
    "items": [
      { "sku": "KB-01",  "name": "Mechanical Keyboard", "qty": 1, "price": 129 },
      { "sku": "DSK-04", "name": "Standing Desk",       "qty": 1, "price": 549 },
      { "sku": "MAT-02", "name": "Desk Mat",             "qty": 2, "price": 25 }
    ],
    "shipping": { "method": "express", "cost": 18.50 },
    "coupons": ["WELCOME10"]
  }
}

Navigation: getting to the data

Everything starts with . — the identity filter, the input itself. From there you navigate by field and index:

Missing keys return null rather than erroring — .order.customer.phone is null. Convenient for exploration, treacherous in scripts; more on that under errors.

Iteration and the pipe

.[] explodes a structure into a stream: each array element (or object value) becomes its own output. The pipe connects filters so each stage works on the last stage's output:

That last table row is the mental unlock: map(f) is nothing but iterate-and-collect. Once you see jq as shell plumbing for JSON, unfamiliar filters decompose into familiar ones.

Filtering and searching

select() passes values that satisfy a condition and drops the rest — the WHERE clause of jq:

Two idioms to internalize: negated sort keys (sort_by(-.price)) for descending order, and // for defaults when a field is null or false.

Arithmetic and statistics

The as $var binding is how you compute with two distant parts of one document — bind the root, navigate away, come back. And 728 divided by 4 units is 182 even, the average price per unit:

.order as $o
| ($o.items | map(.qty * .price) | add) / ($o.items | map(.qty) | add)
# => 182

Reshaping output

Half of jq's value is producing the shape the next tool wants, not just reading what's there:

Object construction {…} builds exactly the fields you name; to_entries turns an object into key/value pairs you can map over; @base64 and friends encode for transport.

Strings that report for duty

String interpolation — \(expression) inside a string — is how jq becomes a report writer:

.order.items[] | "\(.sku): \(.qty) x $\(.price)"
# with -r (raw output):
# KB-01: 1 x $129
# DSK-04: 1 x $549
# MAT-02: 2 x $25

"order #\(.order.id) — \(.order.items | length) items"
# => order #4172 — 3 items

Under -r, string results print unquoted, which is exactly what you want for lines headed to a file or a shell loop.

Errors and missing data

• Missing key: .order.customer.phone → null, silently. Catch it with // "default" or test with has("phone").
• Wrong type: .order.id | .foo errors ("Cannot index number with foo"). Append ? — .foo? — to suppress and get null instead.
• Compile errors: a misspelled function like lengthh fails before any input runs; jq reports jq: 1 compile error with a caret at the offending token.
• Debugging: insert . stages — run .order.items, then .order.items[], then the full pipeline — until the surprise appears.

The 60-second recap

Navigate with .a.b[0], stream with .[], chain with |, filter with select(), transform each with map(), collect with […], bind with as $x, default with //, report with "\(...)" and -r. That's nine ideas and roughly 95% of daily jq. When your data isn't JSON yet, the JSON formatter will tell you why, the JSON viewer shows structure at a glance, and the JSON to YAML converter bridges the config world.

Frequently Asked Questions

Related Tools