Standard JMESPath Functions¶
Standard functions defined by the JMESPath specification.
Summary¶
| Function | Signature | Description |
|---|---|---|
abs |
number -> number |
Returns the absolute value of a number |
avg |
array[number] -> number |
Returns the average of an array of numbers |
ceil |
number -> number |
Returns the smallest integer greater than or equal to the number |
contains |
array\|string, any -> boolean |
Returns true if the subject contains the search value |
ends_with |
string, string -> boolean |
Returns true if the subject ends with the suffix |
floor |
number -> number |
Returns the largest integer less than or equal to the number |
join |
string, array[string] -> string |
Returns array elements joined into a string with a separator |
keys |
object -> array[string] |
Returns an array of keys from an object |
length |
array\|object\|string -> number |
Returns the length of an array, object, or string |
map |
expression, array -> array |
Applies an expression to each element of an array |
max |
array[number]\|array[string] -> number\|string |
Returns the maximum value in an array |
max_by |
array, expression -> any |
Returns the element with maximum value by expression |
merge |
object... -> object |
Merges objects into a single object |
min |
array[number]\|array[string] -> number\|string |
Returns the minimum value in an array |
min_by |
array, expression -> any |
Returns the element with minimum value by expression |
not_null |
any... -> any |
Returns the first non-null argument |
reverse |
array\|string -> array\|string |
Reverses an array or string |
sort |
array[number]\|array[string] -> array |
Sorts an array of numbers or strings |
sort_by |
array, expression -> array |
Sorts an array by expression result |
starts_with |
string, string -> boolean |
Returns true if the subject starts with the prefix |
sum |
array[number] -> number |
Returns the sum of an array of numbers |
to_array |
any -> array |
Converts a value to an array |
to_number |
any -> number |
Converts a value to a number |
to_string |
any -> string |
Converts a value to a string |
type |
any -> string |
Returns the type of a value as a string |
values |
object -> array |
Returns an array of values from an object |
Functions¶
abs¶
Returns the absolute value of a number
Signature: number -> number
Examples:
avg¶
Returns the average of an array of numbers
Signature: array[number] -> number
Examples:
# Simple average
avg([1, 2, 3]) -> 2
# Four numbers
avg([10, 20, 30, 40]) -> 25
# Single element
avg([5]) -> 5
ceil¶
Returns the smallest integer greater than or equal to the number
Signature: number -> number
Examples:
# Round up decimal
ceil(`1.5`) -> 2
# Negative rounds toward zero
ceil(`-1.5`) -> -1
# Integer unchanged
ceil(`5`) -> 5
contains¶
Returns true if the subject contains the search value
Signature: array|string, any -> boolean
Examples:
# Array contains number
contains([1, 2, 3], `2`) -> true
# String contains substring
contains('hello', 'ell') -> true
# Not found
contains([1, 2, 3], `5`) -> false
ends_with¶
Returns true if the subject ends with the suffix
Signature: string, string -> boolean
Examples:
# Ends with suffix
ends_with('hello', 'lo') -> true
# Does not end with
ends_with('hello', 'he') -> false
# File extension
ends_with('test.txt', '.txt') -> true
floor¶
Returns the largest integer less than or equal to the number
Signature: number -> number
Examples:
# Round down decimal
floor(`1.9`) -> 1
# Negative rounds away from zero
floor(`-1.5`) -> -2
# Integer unchanged
floor(`5`) -> 5
join¶
Returns array elements joined into a string with a separator
Signature: string, array[string] -> string
Examples:
# Join with comma
join(', ', ['a', 'b', 'c']) -> \"a, b, c\"
# Join date parts
join('-', ['2024', '01', '15']) -> \"2024-01-15\"
# Join without separator
join('', ['a', 'b', 'c']) -> \"abc\"
keys¶
Returns an array of keys from an object
Signature: object -> array[string]
Examples:
# Get object keys
keys({a: 1, b: 2}) -> [\"a\", \"b\"]
# Keys sorted alphabetically
keys({name: \"John\", age: 30}) -> [\"age\", \"name\"]
# Empty object
keys({}) -> []
length¶
Returns the length of an array, object, or string
Signature: array|object|string -> number
Examples:
# Array length
length([1, 2, 3]) -> 3
# String length
length('hello') -> 5
# Object key count
length({a: 1, b: 2}) -> 2
map¶
Applies an expression to each element of an array
Signature: expression, array -> array
Examples:
# Extract field from objects
map(&a, [{a: 1}, {a: 2}]) -> [1, 2]
# Apply function
map(&length(@), ['a', 'bb', 'ccc']) -> [1, 2, 3]
# Identity mapping
map(&@, [1, 2, 3]) -> [1, 2, 3]
max¶
Returns the maximum value in an array
Signature: array[number]|array[string] -> number|string
Examples:
# Max of numbers
max([1, 3, 2]) -> 3
# Max of strings
max(['a', 'c', 'b']) -> 'c'
# Negative numbers
max([-5, -1, -10]) -> -1
max_by¶
Returns the element with maximum value by expression
Signature: array, expression -> any
Examples:
# Max by field
max_by([{a: 1}, {a: 2}], &a) -> {a: 2}
# Max by age
max_by([{name: 'a', age: 30}, {name: 'b', age: 25}], &age) -> {name: 'a', age: 30}
# Max by length
max_by(['aa', 'b', 'ccc'], &length(@)) -> 'ccc'
merge¶
Merges objects into a single object
Signature: object... -> object
Examples:
# Merge two objects
merge({a: 1}, {b: 2}) -> {a: 1, b: 2}
# Later values override
merge({a: 1}, {a: 2}) -> {a: 2}
# Multiple objects
merge({a: 1}, {b: 2}, {c: 3}) -> {a: 1, b: 2, c: 3}
min¶
Returns the minimum value in an array
Signature: array[number]|array[string] -> number|string
Examples:
# Min of numbers
min([1, 3, 2]) -> 1
# Min of strings
min(['a', 'c', 'b']) -> 'a'
# Negative numbers
min([-5, -1, -10]) -> -10
min_by¶
Returns the element with minimum value by expression
Signature: array, expression -> any
Examples:
# Min by field
min_by([{a: 1}, {a: 2}], &a) -> {a: 1}
# Min by age
min_by([{name: 'a', age: 30}, {name: 'b', age: 25}], &age) -> {name: 'b', age: 25}
# Min by length
min_by(['aa', 'b', 'ccc'], &length(@)) -> 'b'
not_null¶
Returns the first non-null argument
Signature: any... -> any
Examples:
# Skip nulls
not_null(`null`, 'a', 'b') -> \"a\"
# First non-null
not_null('first', 'second') -> \"first\"
# Multiple nulls
not_null(`null`, `null`, `1`) -> 1
reverse¶
Reverses an array or string
Signature: array|string -> array|string
Examples:
# Reverse array
reverse([1, 2, 3]) -> [3, 2, 1]
# Reverse string
reverse('hello') -> 'olleh'
# Empty array
reverse([]) -> []
sort¶
Sorts an array of numbers or strings
Signature: array[number]|array[string] -> array
Examples:
# Sort numbers
sort([3, 1, 2]) -> [1, 2, 3]
# Sort strings
sort(['c', 'a', 'b']) -> ['a', 'b', 'c']
# Empty array
sort([]) -> []
sort_by¶
Sorts an array by expression result
Signature: array, expression -> array
Examples:
# Sort by field
sort_by([{a: 2}, {a: 1}], &a) -> [{a: 1}, {a: 2}]
# Sort by length
sort_by(['bb', 'a', 'ccc'], &length(@)) -> ['a', 'bb', 'ccc']
# Sort by name
sort_by([{name: 'z'}, {name: 'a'}], &name) -> [{name: 'a'}, {name: 'z'}]
starts_with¶
Returns true if the subject starts with the prefix
Signature: string, string -> boolean
Examples:
# Starts with prefix
starts_with('hello', 'he') -> true
# Does not start with
starts_with('hello', 'lo') -> false
# URL protocol
starts_with('https://example.com', 'https') -> true
sum¶
Returns the sum of an array of numbers
Signature: array[number] -> number
Examples:
# Sum of numbers
sum([1, 2, 3]) -> 6
# With negative
sum([10, -5, 3]) -> 8
# Empty array
sum([]) -> 0
to_array¶
Converts a value to an array
Signature: any -> array
Examples:
# String to array
to_array('hello') -> [\"hello\"]
# Array unchanged
to_array([1, 2]) -> [1, 2]
# Number to array
to_array(`5`) -> [5]
to_number¶
Converts a value to a number
Signature: any -> number
Examples:
# String to number
to_number('42') -> 42
# String to float
to_number('3.14') -> 3.14
# Number unchanged
to_number(`5`) -> 5
to_string¶
Converts a value to a string
Signature: any -> string
Examples:
# Number to string
to_string(`42`) -> \"42\"
# Boolean to string
to_string(`true`) -> \"true\"
# String unchanged
to_string('hello') -> \"hello\"
type¶
Returns the type of a value as a string
Signature: any -> string
Examples:
# String type
type('hello') -> \"string\"
# Number type
type(`42`) -> \"number\"
# Array type
type([1, 2]) -> \"array\"
# Object type
type({a: 1}) -> \"object\"
values¶
Returns an array of values from an object
Signature: object -> array
Examples: