Expression Syntax¶
JMESPath expression syntax reference.
Identifiers¶
Access object properties by name:
Index Expressions¶
Access array elements by index (0-based):
echo '{"items": ["a", "b", "c"]}' | jpx 'items[0]'
# "a"
echo '{"items": ["a", "b", "c"]}' | jpx 'items[-1]'
# "c"
Slicing¶
Extract array slices with [start:stop:step]:
echo '[0, 1, 2, 3, 4, 5]' | jpx '[0:3]'
# [0, 1, 2]
echo '[0, 1, 2, 3, 4, 5]' | jpx '[::2]'
# [0, 2, 4]
echo '[0, 1, 2, 3, 4, 5]' | jpx '[::-1]'
# [5, 4, 3, 2, 1, 0]
Wildcard¶
Project all elements with *:
Flatten¶
Flatten nested arrays with []:
Filter Expressions¶
Filter arrays with [?expression]:
echo '[{"age": 25}, {"age": 17}, {"age": 30}]' | jpx '[?age > `18`]'
# [{"age": 25}, {"age": 30}]
echo '[{"name": "Alice", "active": true}, {"name": "Bob", "active": false}]' | jpx '[?active].name'
# ["Alice"]
Comparison Operators¶
| Operator | Description |
|---|---|
== |
Equal |
!= |
Not equal |
< |
Less than |
<= |
Less than or equal |
> |
Greater than |
>= |
Greater than or equal |
Logical Operators¶
| Operator | Description |
|---|---|
&& |
Logical AND |
\|\| |
Logical OR |
! |
Logical NOT |
Pipe Expressions¶
Chain expressions with |:
Multi-Select List¶
Create arrays from multiple expressions:
Multi-Select Hash¶
Create objects from multiple expressions:
echo '{"first": "Alice", "last": "Smith", "age": 30}' | jpx '{name: first, surname: last}'
# {"name": "Alice", "surname": "Smith"}
Literal Values¶
Bare null, true, and false are field names in both default and strict mode.
Single-quote the whole shell expression to pass backticks without escaping them.
See the bare-literals compatibility decision for
tested comparisons, numeric ambiguities, and shell/query-file recipes.
Use backticks for literal values:
# Literal number
echo '{"items": [1, 2, 3]}' | jpx '[?@ > `1`]'
# Literal string
echo '{"items": ["a", "b"]}' | jpx 'contains(items, `"a"`)'
# Literal array
echo '{}' | jpx '`[1, 2, 3]`'
# Literal object
echo '{}' | jpx '`{"key": "value"}`'
Current Node¶
Reference the current node with @:
Function Calls¶
Call functions with function_name(arg1, arg2, ...):
echo '{"items": [1, 2, 3]}' | jpx 'length(items)'
# 3
echo '{"name": "hello"}' | jpx 'upper(name)'
# "HELLO"
echo '{"a": [1, 2], "b": [3, 4]}' | jpx 'merge(a, b)'
# [1, 2, 3, 4]
Functions can take literal JSON values as arguments using backticks:
# Apply default values to an object
echo '{"name": "Alice"}' | jpx 'defaults(@, `{"role": "user", "active": true}`)'
# {"name": "Alice", "role": "user", "active": true}
# Build an object from key-value pairs
echo 'null' | jpx 'from_items(`[["a", 1], ["b", 2]]`)'
# {"a": 1, "b": 2}
Expression References¶
Use & for expression references (used with higher-order functions):
echo '[{"age": 30}, {"age": 20}]' | jpx 'sort_by(@, &age)'
# [{"age": 20}, {"age": 30}]
echo '[1, 2, 3]' | jpx 'map(&@ * `2`, @)'
# [2, 4, 6]
An expression reference is only valid as a function argument, or as a let
binding value that is later passed to a function:
echo '[{"age": 30}, {"age": 20}]' | jpx 'let $by_age = &age in sort_by(@, $by_age)'
# [{"age": 20}, {"age": 30}]
Anywhere else, such as a | &b or [&a], is a parse error.
Let Expressions (JEP-18)¶
Bind intermediate results to variables with let:
echo '{"people": [{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]}' \
| jpx 'let $adults = people[?age > `28`] in $adults[*].name'
# ["Alice"]
echo '{"data": [3, 1, 4]}' \
| jpx 'let $s = sort(data), $n = length(data) in {sorted: $s, count: $n}'
# {"sorted": [1, 3, 4], "count": 3}
Variables are prefixed with $ and scoped to the in body. Multiple bindings are separated by commas. See the Let Expressions guide for full details.
Note
Let expressions are disabled in strict mode since they are a JEP-18 extension.