jq Filters and Transformations

jq•Permalink

Advanced jq patterns for regex, booleans, dates, math, recursive descent, filtering, and output shaping.

View

Standard Detailed Compact

Export

Copy the compact sheet, download it, or print it.

Download

`D` dense toggle · `C` copy all

Boolean Logic

Predicates and truthy tests.

Logical AND

Filter items that satisfy two conditions.

↗#

bashANYjqbooleanand

bash

echo '[{"env":"prod","healthy":true},{"env":"dev","healthy":true}]' | jq '.[] | select(.env == "prod" and .healthy)'

Combine predicates with `and` and `or`.

Logical OR

Match either of two conditions.

↗#

bashANYjqbooleanor

bash

echo '[{"role":"admin"},{"role":"editor"}]' | jq '.[] | select(.role == "admin" or .role == "owner")'

Great for whitelists and matching multiple states.

Logical NOT

Invert a predicate.

↗#

bashANYjqbooleannot

bash

echo '[{"active":true},{"active":false}]' | jq '.[] | select(.active | not)'

`not` is frequently used inside filters.

Test membership with IN

Check whether a value appears in a stream.

↗#

bashANYjqmembershipboolean

bash

echo '"b"' | jq 'IN("a", "b", "c")'

Useful for simple membership tests in jq expressions.

Regex and Text Processing

Pattern matching and text extraction.

Test regex match

Return true if a string matches a pattern.

↗#

bashANYjqregextest

bash

echo '"alice@example.com"' | jq 'test("@example.com$")'

Use `test()` for boolean regex checks.

Get regex match details

Return structured regex match metadata.

↗#

bashANYjqregexmatch

bash

echo '"order-123"' | jq 'match("[0-9]+")'

`match()` returns offsets, lengths, and captured text.

Capture named regex groups

Extract named groups into an object.

↗#

bashANYjqregexcapture

bash

echo '"alice@example.com"' | jq 'capture("(?<user>[^@]+)@(?<domain>.+)")'

`capture()` is perfect for structured extraction from strings.

Replace first regex match

Replace text using a regex pattern.

↗#

bashANYjqregexreplace

bash

echo '"hello world"' | jq 'sub("world"; "jq")'

Use `sub()` for one replacement and `gsub()` for all matches.

Replace all matches

Replace every instance of a pattern.

↗#

bashANYjqregexgsub

bash

echo '"a-b-c"' | jq 'gsub("-"; ":")'

Very useful for cleanup and normalization.

Split with regex

Split a string using a regex separator.

↗#

bashANYjqregexsplit

bash

echo '"a, b; c"' | jq 'splits("[,;] ?")'

`splits()` emits values as a stream, which is handy for pipelines.

Numbers and Math

Math functions and numeric transforms.

Floor number

Round down to nearest integer.

↗#

bashANYjqmathfloor

bash

echo '3.9' | jq 'floor'

Useful for timestamps and bucketing.

Ceiling number

Round up to nearest integer.

↗#

bashANYjqmathceil

bash

echo '3.1' | jq 'ceil'

Handy for quota and size calculations.

Round number

Round to the nearest integer.

↗#

bashANYjqmathround

bash

echo '3.6' | jq 'round'

Basic rounding helper.

Absolute value

Return the absolute value of a number.

↗#

bashANYjqmathabs

bash

echo '-42' | jq 'abs'

Simple but useful in transformations.

Generate numeric range

Create a sequence of integers.

↗#

bashANYjqrangemath

bash

jq -n '[range(0; 5)]'

Great for synthetic data and loops.

Bucket numbers

Convert numbers into 10-point buckets.

↗#

bashANYjqmathbucketing

bash

echo '[3,14,27,39]' | jq 'map((./10 | floor) * 10)'

Common analytics-style transformation.

Dates and Time

Timestamp parsing and formatting.

Current Unix time

Get the current time as Unix epoch seconds.

↗#

bashANYjqtimenow

bash

jq -n 'now'

Useful for generated metadata and quick timestamps.

Unix time to ISO string

Format epoch seconds as an ISO-like UTC string.

↗#

bashANYjqtimetodate

bash

jq -n 'now | todate'

Human-friendly UTC date output.

ISO string to Unix time

Parse an ISO timestamp into epoch seconds.

↗#

bashANYjqtimefromdateiso8601

bash

echo '"2025-01-15T12:34:56Z"' | jq 'fromdateiso8601'

Ideal for comparing timestamps numerically.

Parse custom date format

Parse a custom-formatted date string.

↗#

bashANYjqtimestrptime

bash

echo '"2025-01-15 12:34:56"' | jq 'strptime("%Y-%m-%d %H:%M:%S")'

Returns a time array, which you can convert with `mktime`.

Format epoch as custom string

Render timestamps using a custom format.

↗#

bashANYjqtimestrftime

bash

jq -n 'now | strftime("%Y-%m-%d")'

Great for filenames and daily reports.

Encoding and Recursion

Recursive descent, encoding, and document-wide transforms.

Find all keys recursively

Emit every key in nested objects.

↗#

bashANYjqrecursivekeys

bash

echo '{"a":1,"b":{"c":2}}' | jq '.. | objects | keys[]'

Useful for schema discovery and audits.

Find all numbers recursively

Emit every number in a document.

↗#

bashANYjqrecursivenumbers

bash

echo '{"a":1,"b":[2,{"c":3}]}' | jq '.. | numbers'

Recursive descent combines well with type filters like `numbers` and `strings`.

JSON-encode raw text

Turn raw text into a valid JSON string.

↗#

bashANYjqencodingjson

bash

printf 'hello
world
' | jq -Rs '.'

Excellent for embedding arbitrary text into JSON payloads.

HTML-escape a string

Escape special HTML characters.

↗#

bashANYjqencodinghtml

bash

echo '"<b>hello</b>"' | jq -r '@html'

Useful for templating and safe output.

Shell-escape a string

Produce a shell-safe quoted string.

↗#

bashANYjqencodingshell

bash

echo '"hello world"' | jq -r '@sh'

Great when generating shell commands from JSON data.

More in jq

jq CLI Recipes

Real-world jq commands for APIs, cloud tooling, DevOps output, reporting, logs, and shell scripting.

jq Arrays and Objects

Deep reference for jq arrays, objects, grouping, entries, path updates, reshaping, and structural manipulation.

jq Cheat Sheet

Core jq syntax, filters, selectors, arrays, objects, variables, sorting, grouping, formatting, and shell-friendly usage.

Recommended next

No recommendations yet.

Browse all sheets →