jq101Runs locally

jq cheatsheet

Start here

Identity, navigation, iteration, and composition. Explore 10 examples, then try one against the included input or your own data.

jq examples

10 examplesIdentity, navigation, iteration, and composition.
Start here

Return the input unchanged

The identity filter is the smallest useful jq program.

.
Input and expected output
Input
{"hello":"world"}
Expected output
{
  "hello": "world"
}
Start here

Read a nested field

Chain object identifiers to walk through nested objects.

.user.profile.name
Input and expected output
Input
{"user":{"profile":{"name":"Ada"}}}
Expected output
"Ada"
Start here

Read a key with punctuation

Use bracket notation when a key is not a valid jq identifier.

.["first-name"]
Input and expected output
Input
{"first-name":"Ada"}
Expected output
"Ada"
Start here

Ignore a missing optional field

The optional operator suppresses an error when the input cannot be indexed.

.users[] | .profile?.email?
Input and expected output
Input
{"users":[{"profile":{"email":"a@example.test"}},null]}
Expected output
"a@example.test"
null

A missing object field normally yields null; ? is most useful when the input type may differ.

Start here

Emit every array item

.[] is a generator: one input can produce many output values.

.users[]
Input and expected output
Input
{"users":["Ada","Grace","Linus"]}
Expected output
"Ada"
"Grace"
"Linus"
Start here

Pick an array item

Array indexes are zero-based; negative indexes count from the end.

.users[-1]
Input and expected output
Input
{"users":["Ada","Grace","Linus"]}
Expected output
"Linus"
Start here

Take an array slice

A slice includes the start index and excludes the end index.

.[1:4]
Input and expected output
Input
[0,1,2,3,4]
Expected output
[
  1,
  2,
  3
]
Start here

Compose filters with a pipe

The right side runs once for every value emitted on the left.

.users[] | .name
Input and expected output
Input
{"users":[{"name":"Ada"},{"name":"Grace"}]}
Expected output
"Ada"
"Grace"
Start here

Emit more than one result

The comma operator sends both filters the same input.

.id, .name
Input and expected output
Input
{"id":42,"name":"Ada"}
Expected output
42
"Ada"
Start here

Collect a stream into an array

Array construction collects all emitted values into one array.

[.users[].name]
Input and expected output
Input
{"users":[{"name":"Ada"},{"name":"Grace"}]}
Expected output
[
  "Ada",
  "Grace"
]