Skip to content

JMESPath Primer

JMESPath is a query language for JSON. This primer covers the essentials you need to start using jpx effectively.

Basic Syntax

Accessing Fields

Use dot notation to access object fields:

echo '{"name": "Alice", "age": 30}' | jpx 'name'
# "Alice"

echo '{"user": {"profile": {"email": "a@b.com"}}}' | jpx 'user.profile.email'
# "a@b.com"

Array Access

Use brackets for array elements:

echo '["a", "b", "c"]' | jpx '[0]'
# "a"

echo '["a", "b", "c"]' | jpx '[-1]'
# "c" (last element)

echo '["a", "b", "c", "d", "e"]' | jpx '[1:3]'
# ["b", "c"] (slice)

Wildcard Projection

Use [*] to project all array elements:

echo '[{"name": "Alice"}, {"name": "Bob"}]' | jpx '[*].name'
# ["Alice", "Bob"]

Filtering

Filter arrays with [?expression]:

# Filter by field value
echo '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}]' | \
  jpx '[?age > `28`]'
# [{"name": "Alice", "age": 30}]

# Multiple conditions
echo '[{"name": "Alice", "active": true}, {"name": "Bob", "active": false}]' | \
  jpx '[?active == `true`].name'
# ["Alice"]

Note: Literal values use backticks: `28`, `true`, `"string"`

Functions

JMESPath has built-in functions. jpx extends these with 400+ more.

Standard Functions (26)

These work in all JMESPath implementations:

echo '[3, 1, 4, 1, 5]' | jpx 'length(@)'
# 5

echo '[3, 1, 4, 1, 5]' | jpx 'sort(@)'
# [1, 1, 3, 4, 5]

echo '{"a": 1, "b": 2}' | jpx 'keys(@)'
# ["a", "b"]

The @ symbol refers to the current element.

Extension Functions (370+)

jpx adds powerful functions for real-world tasks:

echo '{"name": "hello world"}' | jpx 'upper(name)'
# "HELLO WORLD"

echo '[1, 2, 2, 3, 3, 3]' | jpx 'unique(@)'
# [1, 2, 3]

echo '[10, 20, 30, 40, 50]' | jpx 'median(@)'
# 30

Use --strict mode to limit to standard functions only.

Pipes

Chain operations with |:

echo '[{"n": "Alice"}, {"n": "Bob"}, {"n": "Alice"}]' | \
  jpx '[*].n | unique(@) | sort(@)'
# ["Alice", "Bob"]

Multi-Select

Lists

Create arrays with [expr1, expr2]:

echo '{"a": 1, "b": 2, "c": 3}' | jpx '[a, c]'
# [1, 3]

Objects

Create objects with {key: expr}:

echo '{"first": "Alice", "last": "Smith", "age": 30}' | \
  jpx '{name: first, years: age}'
# {"name": "Alice", "years": 30}

Common Patterns

Transform Array Elements

echo '{"users": [{"name": "alice"}, {"name": "bob"}]}' | \
  jpx 'users[*].{username: name, active: `true`}'
# [{"username": "alice", "active": true}, {"username": "bob", "active": true}]

Filter and Project

echo '{"items": [{"price": 10}, {"price": 50}, {"price": 25}]}' | \
  jpx 'items[?price > `20`].price'
# [50, 25]

Aggregate

echo '{"sales": [100, 200, 150]}' | jpx 'sum(sales)'
# 450

echo '{"scores": [85, 92, 78, 95]}' | jpx 'avg(scores)'
# 87.5

Nested Access with Defaults

echo '{"user": {}}' | jpx 'user.name || `"unknown"`'
# "unknown"

Finding Functions

Don't memorize 400 functions. Search for what you need:

# Search by keyword
jpx --search "date"

# Get function details
jpx --describe format_date

# List by category
jpx --list-category string

Next Steps