jq Explorer

What is jq?

jq is a lightweight, command-line JSON processor. It lets you slice, filter, map, and transform JSON data with a concise expression language. In your browser this tool runs jq via WebAssembly — no server required.

Basic syntax

.foo

Object field access. Returns the value of key foo.

.foo.bar

Nested field access.

.foo?

Optional field — suppresses errors if foo doesn't exist.

.[0]

Array index. .[0] is the first element, .[-1] the last.

.[2:5]

Array slice from index 2 up to (not including) 5.

.[]

Iterate — outputs each element of an array or each value of an object.

Operators & expressions

. + 1

Arithmetic: add, subtract, multiply, divide work on numbers.

"Hello, " + .name

String concatenation.

.a // .b

Alternative operator — uses .b if .a is false or null.

.x == .y

Equality test. Also !=, <, <=, >, >=.

.a and .b

Boolean and / or / not.

if .x > 0 then "pos" else "neg" end

Conditional expression.

Pipe & comma

.foo | .bar

Pipe — passes the output of the left into the right, like Unix pipes.

.foo, .bar

Comma — produces multiple outputs (one per value).

.[] | .name

Iterate the array, then extract .name from each element.

Built-in functions

length

Length of a string, array, or object (number of keys).

keys

Array of an object's keys, sorted.

values

Array of an object's values.

has("foo")

Returns true if the object has key foo.

in({"a":1})

Returns true if the input key exists in the object.

map(.x)

Apply a filter to every element of an array.

map_values(.x + 1)

Apply a filter to every value of an object.

select(.age > 18)

Filter — emits the input only if the condition is true.

empty

Produces no output (useful to discard values).

add

Sum an array of numbers, or concatenate strings/arrays.

any

True if any element satisfies the condition.

all

True if all elements satisfy the condition.

flatten

Flatten nested arrays into a single array.

unique

Remove duplicate values from an array.

unique_by(.x)

Remove duplicates based on a key expression.

group_by(.x)

Group array elements by a key expression.

sort_by(.x)

Sort an array by a key expression.

min_by(.x) / max_by(.x)

Minimum / maximum element by key.

to_entries

Convert object to [{key, value}] array.

from_entries

Convert [{key, value}] array back to an object.

with_entries(.value += 1)

Shorthand for to_entries | map(…) | from_entries.

type

Returns the type string: "null", "boolean", "number", "string", "array", "object".

strings / numbers / arrays / objects / booleans / nulls

Select only values of that type.

tostring / tonumber

Convert between strings and numbers.

ascii_downcase / ascii_upcase

Change string case.

ltrimstr(s) / rtrimstr(s)

Strip a prefix / suffix from a string.

split(",") / join(",")

Split a string into an array, or join an array into a string.

test("regex")

Test a string against a regular expression.

capture("(?:\\d{4})")

Extract named capture groups from a string as an object.

env

Access environment variables as an object.

path(.foo.bar)

Returns the path expression as an array of keys.

getpath(["a","b"])

Get a value at an array path.

setpath(["a","b"]; 1)

Set a value at an array path.

delpaths([["a"]])

Delete values at the given paths.

del(.foo)

Delete a key from an object or element from an array.

recurse

Recursively descend through nested structures.

walk(f)

Apply f to every node bottom-up in a JSON document.

tojson / fromjson

Encode to / decode from a JSON string.

error(msg)

Throw an error with a message.

debug

Print the value to stderr and pass it through unchanged.

limit(n; expr)

Emit at most n outputs from expr.

first(expr) / last(expr)

Emit only the first or last output of expr.

range(n) / range(from; to)

Emit integers 0..n-1 or from..to-1.

indices(s)

Find all positions of a substring or element.

index(s) / rindex(s)

First / last position of a substring or element.

inside(b)

Returns true if the input is contained within b.

contains(b)

Returns true if b is contained within the input.

Object & array construction

{name: .name, age: .age}

Build a new object by picking fields.

{(.key): .value}

Dynamic key — parentheses evaluate the key expression.

[.[] | select(.active)]

Build an array from filtered results.

[range(5)]

Build an array [0,1,2,3,4].

Variables & definitions

.foo as $x | $x + $x

Bind a value to a variable with as $name.

def double(x): x * 2; double(21)

Define a reusable function with def.

label $out | foreach .[] as $x (0; . + $x; if . > 10 then ., break $out else . end)

foreach / label-break for early exit in streaming scenarios.

Useful one-liners