Which Built-in Functions Are Supported by JMESPath?

The built-in functions of JMESPath support the following data types:

number (integer and double-precision floating-point format in JSON)
string
boolean (true or false)
array (an ordered sequence of values)
object (an unordered collection of key-value pairs)
expression (denoted by &expression)
null

Built-in functions support different data types, as described in the following table. The special character @ in function arguments indicates that the current result is passed to the function as an input parameter.

**Table 1** Built-in functions supported by JMESPath expressions
Built-in Function	Input Data Type	Output Data Type	Description	Example
abs	number	number	Returns the absolute value of the provided argument.	Expression: abs(1) Final result: 1 Expression: abs(-1) Final result: 1
avg	array[number]	number	Returns the average of the elements in the provided array.	Current result: [10, 15, 20] Expression: avg(@) Final result: 15
ceil	number	number	Returns the next highest integer value by rounding up if necessary.	Expression: ceil(`1.001`) Final result: 2
contains	array\|string, any	boolean	Returns true if the first given argument contains the second one, or otherwise returns false.	Expression: contains('foobar','foo') Final result: true Current result: ["a", "b"] Expression: contains(@, 'a') Final result: true
ends_with	string, string	boolean	Returns true if the first character string ends with the second one, or otherwise returns false.	Current result: foobarbaz Expression: ends_with(@,'baz') Final result: true
floor	number	number	Returns the next lowest integer value by rounding down if necessary.	Expression: floor(`1.001`) Final result: 1
join	string, array[string]	string	Returns all of the elements from the provided character string array joined using the given string argument as a separator.	Current result: ["a", "b"] Expression: join(',', @) Final result: "a, b"
keys	object	array	Returns an array containing the keys of the provided JSON object. Because JSON hashes are inherited and unordered, the keys associated with the provided object are also inherited and unordered. Implementations are not required to return keys in any specific order.	Current result: {"foo": "baz", "bar": "bam"} Expression: keys(@) The final result could be as follows: ["foo", "bar"] ["bar", "foo"] Current result: {} Expression: keys(@) Final result: []
length	string\|array\|object	number	Returns the length of the given argument using the following type rules: 1. string: Returns the number of characters in the string. 2. array: Returns the number of elements in the array. 3. object: Returns the number of key-value pairs in the object.	Current result: current Expression: length(@) Final result: 7 Current result: ["a", "b", "c"] Expression: length(@) Final result: 3 Current result: {"foo": "bar", "baz": "bam"} Expression: length(@) Final result: 2
map	expression->any->any, array[any]	array[any]	Applies the expression in the input argument to every element in the array, and returns the array of results. An element of length N will produce a return array of length N. Unlike a projection, map() will include the result of applying the expression for every element in the elements array, even if the result is null.	Current result: {"array": [{"foo": "a"}, {"foo": "b"}, {}, [], {"foo": "f"}]} Expression: map(&foo, array) Final result: ["a", "b", null, null, "f"] Current result: [[1, 2, 3, [4]], [5, 6, 7, [8, 9] ]] Expression: map(&[], @) Final result: [[1, 2, 3, 4], [5, 6, 7, 8, 9]]
max	array[number]\|array[string]	number	Returns the largest number in the provided array argument.	Current result: [10, 15] Expression: max(@) Final result: 15 Current result: ["abc", "drb"] Expression: max(@) Final result: drb
max_by	array, expression->number\|expression->string	any	Returns the maximum element in an array by using the expression as a comparison key.	Current result: [{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}] For the preceding current result: Expression: max_by(@, &age) Final result: {"age": 50, "age_str": "50", "name": "a"} Expression: max_by(@, &age).age Final result: 50 Expression: max_by(@, &to_number(age_str)) Final result: {"age": 50, "age_str": "50", "name": "a"}
merge	[object [, object ...]]	object	Accepts one or more objects as arguments, and returns a single object with subsequent objects merged. The key-value pairs of each subsequent object are added to the preceding object. This function is used to combine multiple objects into one. You can think of this as the first object being the base object, and each subsequent argument being the overrides that are applied to the base object.	Expression: merge(`{"a": "b"}`, `{"c": "d"}`) Final result: {"a": "b", "c": "d"} Expression: merge(`{"a": "b"}`, `{"a": "override"}`) Final result: {"a": "override"} Expression: merge(`{"a": "x", "b": "y"}`, `{"b": "override", "c": "z"}`) Final result: {"a": "x", "b": "override", "c": "z"}
min	array[number]\|array[string]	number	Returns the smallest number in the provided array argument.	Current result: [10, 15] Expression: min(@) Final result: 10 Current result: ["a", "b"] Expression: min(@) Final result: "a"
min_by	array, expression->number\|expression->string	any	Returns the smallest element in an array using the expression as a comparison key.	Current result: {"people": [{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}]} For the preceding current result: Expression: min_by(people, &age) Final result: {"age": 30, "age_str": "30", "name": "b"} Expression: min_by(people, &age).age Final result: 30 Expression: min_by(people, &to_number(age_str)) Final result: {"age": 30, "age_str": "30", "name": "b"}
not_null	[any [, any ...]]	any	This function accepts one or more arguments, and evaluates them in order until a non-null argument is encountered. If the values of all arguments as resolved as null, KooCLI displays an error message and outputs the original JSON result.	Current result: {"a": null, "b": null, "c": [], "d": "foo"} Expression: not_null(no_exist, a, b, c, d) Final result: [] Current result: {"a": null, "b": null, "c": [], "d": "foo"} Expression: not_null(a, b, `null`, d, c) Final result: "foo" Current result: {"a": null, "b": null, "c": [], "d": "foo"} Expression: not_null(a, b) Final result: null
reverse	string\|array	string\|array	Reverses the order of the input argument.	Current result: [0, 1, 2, 3, 4] Expression: reverse(@) Final result: [4, 3, 2, 1, 0] Current result: [] Expression: reverse(@) Final result: [] Current result: ["a", "b", "c"] Expression: reverse(@) Final result: ["c", "b", "a"] Current result: "abcd" Expression: reverse(@) Final result: "dcba"
sort	array[number]\|array[string]	array	Accepts an array argument and returns the sorted elements as an array. The array must be a list of strings or numbers. Strings are sorted based on a dictionary.	Current result: ["b", "a", "c"] Expression: sort(@) Final result: ["a", "b", "c"] Current result: [1, 4, 2] Expression: sort(@) Final result: [1, 2, 4]
sort_by	array, expression->number\|expression->string	-	Sorts an array using an expression as the sort key. For each element in the array of elements, the expression is applied and the result value is used as the key for sorting the elements. sort_by follows the same sorting logic as the sort function.	Current result: {"people": [{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}]} For the preceding current result: Expression: sort_by(people, &age)[].age Final result: [30, 40, 50] Expression: sort_by(people, &age)[0] Final result: {"age": 30, "age_str": "30", "name": "b"} Expression: sort_by(people, &to_number(age_str))[1] Final result: {"age": 40, "age_str": "40", "name": c}
starts_with	string, string	boolean	Returns true if the first argument starts with the second one, or otherwise returns false.	Current result: foobarbaz Expression: starts_with(@, 'foo') Final result: true Current result: foobarbaz Expression: starts_with(@,'baz') Final result: false Current result: foobarbaz Expression: starts_with(@, 'f') Final result: true
sum	array[number]	number	Returns the sum of the provided array argument. An empty array will produce a return value of 0.	Current result: [10, 15] Expression: sum(@) Final result: 25 Current result: [] Expression: sum(@) Final result: 0
to_array	any	array	array: Returns the passed value. number\|string\|object\|boolean: Returns a one-element array containing the passed argument.	Expression: to_array(`[1, 2]`) Final result: [1, 2] Expression: to_array('string') Final result: ["string"] Expression: to_array(`0`) Final result: [0] Expression: to_array(`true`) Final result: [true] Expression: to_array(`{"foo": "bar"}`) Final result: [{"foo": "bar"}]
to_string	any	string	string: Returns the passed value. number\|array\|object\|boolean: The JSON encoded value of the object.	Expression: to_string(`2`) Final result: 2 Expression: to_string(`[]`) Final result: "[]" Expression: to_string(false) Final result: "null"
to_number	any	number	string: Returns the parsed number. number: Returns the passed value. array\|object\|boolean\|null: KooCLI displays an error message and outputs the original JSON result.	Expression: to_number(`2.3`) Final result: 2.3 Expression: to_number(`2`) Final result: 2
type	array\|object\|string\|number\|boolean\|null	string	Returns the data type of the given argument as a string value. The return value must be one of the following: "number" "string" "boolean" "array" "object" "null"	Expression: type('foo') Final result: "string" Expression: type(`true`) Final result: "boolean" Expression: type(`null`) Final result: "null" Expression: type(`123`) Final result: number Expression: type(`123.05`) Final result: number Expression: type(`[1,2]`) Final result: "array" Current result: {"abc": "123"} Expression: type(@) Final result: "object"
values	object	array	Returns an array of values of the provided JSON object. Because JSON hashes are inherited and unordered, the values associated with the provided object are also inherited and unordered. Implementations are not required to return values of the JSON object in any specific order.	Current result: {"a": "first", "b": "second", "c": "third"} Expression: values(@) The final result could be as follows: ["first", "second", "third"] ["first", "third", "second"] ["second", "first", "third"] ["second", "third", "first"] ["third", "first", "second"] ["third", "second", "first"]