Which Built-in Functions Are Supported by JMESPath?

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"]