更新时间:2022-07-07 GMT+08:00

JMESPath支持的内置函数有哪些?

JMESPath的内置函数支持的数据类型包括:

  • number(json中的整数和双精度浮点格式)
  • string
  • boolean(true 或 false)
  • array(有序的,值序列)
  • object(键值对的无序集合)
  • expression(用&expression表示的表达式)
  • null

各内置函数支持的数据类型不同。具体如下表。函数参数中一个特殊字符“@”代表将当前结果作为入参传递给函数:

表1 JMESPath表达式支持的内置函数

内置函数

入参数据类型

出参数据类型

用途

内置函数使用示例

abs

number

number

返回所提供参数的绝对值。

  • 表达式:abs(1)

    最终结果:1

  • 表达式:abs(-1)

    最终结果:1

avg

array[number]

number

返回所提供数组中元素的平均值。

当前结果:[10, 15, 20]

表达式:avg(@)

最终结果:15

ceil

number

number

通过向上舍入返回下一个整数值。

表达式:ceil(`1.001`)

最终结果:2

contains

array|string, any

boolean

如果给定的两个参数中,前者包含后者,则返回true,否则此函数返回false。

  • 表达式:contains('foobar', 'foo')

    最终结果:true

  • 当前结果:["a", "b"]

    表达式:contains(@, 'a')

    最终结果:true

ends_with

string, string

boolean

如果入参的两个字符串中,前者以后者结尾,则返回true,否则此函数返回false。

当前结果:foobarbaz

表达式:ends_with(@,'baz')

最终结果:true

floor

number

number

通过向下四舍五入返回下一个整数值。

表达式:floor(`1.001`)

最终结果:1

join

string, array[string]

string

返回所提供的字符串数组中使用给定字符串参数作为每个元素之间的分隔符连接在一起的所有元素。

当前结果:["a", "b"]

表达式:join(',', @)

最终结果:“a, b”

keys

object

array

返回包含所提供json对象的键的数组。由于json哈希是继承的无序的,因此与提供的入参对象关联的键是继承的无序的。实现不需要以任何特定顺序返回键的数组。

  • 当前结果:{"foo": "baz", "bar": "bam"}

    表达式:keys(@)

    最终结果可能为:

    • ["foo", "bar"]
    • ["bar", "foo"]
  • 当前结果:{}

    表达式:keys(@)

    最终结果:[]

length

string|array|object

number

使用以下类型规则返回给定参数的长度:

1.string:返回字符串中的字符个数。

2.array:返回数组中元素的个数。

3.object:返回对象中键值对的个数。

  • 当前结果:“current”

    表达式:length(@)

    最终结果:7

  • 当前结果:["a", "b", "c"]

    表达式:length(@)

    最终结果:3

  • 当前结果:{"foo": "bar", "baz": "bam"}

    表达式:length(@)

    最终结果:2

map

expression->any->any, array[any]

array[any]

将入参中的表达式应用于入参中的数组的每个元素,并返回结果数组。长度为N的元素将产生长度为N的返回数组。

与投影不同,map()将包括为元素数组中的每个元素应用入参中的表达式的结果,即使结果为null。

  • 当前结果:{"array": [{"foo": "a"}, {"foo": "b"}, {}, [], {"foo": "f"}]}

    表达式:map(&foo, array)

    最终结果:["a", "b", null, null, "f"]

  • 当前结果:[[1, 2, 3, [4]], [5, 6, 7, [8, 9]]]

    表达式:map(&[], @)

    最终结果:[[1, 2, 3, 4], [5, 6, 7, 8, 9]]

max

array[number]|array[string]

number

返回所提供的数组参数中的最大元素。

  • 当前结果:[10, 15]

    表达式:max(@)

    最终结果:15

  • 当前结果:["abc", "drb"]

    表达式:max(@)

    最终结果:“drb”

max_by

array, expression->number|expression->string

any

使用入参中的表达式作为比较键返回数组中的最大元素。

当前结果:[{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}]

对于如上当前结果:

  • 表达式:max_by(@, &age)

    最终结果:{"age": 50, "age_str": "50", "name": "a"}

  • 表达式:max_by(@, &age).age

    最终结果:50

  • 表达式:max_by(@, &to_number(age_str))

    最终结果:{"age": 50, "age_str": "50", "name": "a"}

merge

[object [, object ...]]

object

接受1个或多个对象,并返回一个合并了后续对象的单个对象。每个后续对象的键/值对都会添加到前面的对象中。此函数用于将多个对象合并为一个对象。您可以将其视为第一个对象是基对象,每个后续参数都是用于基对象的覆盖。

  • 表达式:merge(`{"a": "b"}`, `{"c": "d"}`)

    最终结果:{"a": "b", "c": "d"}

  • 表达式:merge(`{"a": "b"}`, `{"a": "override"}`)

    最终结果:{"a": "override"}

  • 表达式:merge(`{"a": "x", "b": "y"}`, `{"b": "override", "c": "z"}`)

    最终结果:{"a": "x", "b": "override", "c": "z"}

min

array[number]|array[string]

number

返回所提供的数组参数中的最小元素。

  • 当前结果:[10, 15]

    表达式:min(@)

    最终结果:10

  • 当前结果:["a", "b"]

    表达式:min(@)

    最终结果:“a”

min_by

array, expression->number|expression->string

any

使用入参中的表达式作为比较键返回数组中的最小元素。

当前结果:{"people": [{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}]}

对于如上当前结果:

  • 表达式:min_by(people, &age)

    最终结果:{"age": 30, "age_str": "30", "name": "b"}

  • 表达式:min_by(people, &age).age

    最终结果:30

  • 表达式:min_by(people, &to_number(age_str))

    最终结果:{"age": 30, "age_str": "30", "name": "b"}

not_null

[any [, any ...]]

any

此函数接收一个或多个参数,并将按顺序解析它们,直到遇到非空参数。如果所有参数值都解析为null,KooCLI会提示错误告警信息并输出原json结果。

  • 当前结果:{"a": null, "b": null, "c": [], "d": "foo"}

    表达式:not_null(no_exist, a, b, c, d)

    最终结果:[]

  • 当前结果:{"a": null, "b": null, "c": [], "d": "foo"}

    表达式:not_null(a, b, `null`, d, c)

    最终结果:"foo"

  • 当前结果:{"a": null, "b": null, "c": [], "d": "foo"}

    表达式:not_null(a, b)

    最终结果:null

reverse

string|array

string|array

反转入参的顺序。

  • 当前结果:[0, 1, 2, 3, 4]

    表达式:reverse(@)

    最终结果:[4, 3, 2, 1, 0]

  • 当前结果:[]

    表达式:reverse(@)

    最终结果:[]

  • 当前结果:["a", "b", "c"]

    表达式:reverse(@)

    最终结果:["c", "b", "a"]

  • 当前结果:"abcd"

    表达式:reverse(@)

    最终结果:"dcba"

sort

array[number]|array[string]

array

此函数接受数组参数,并将排序后的数组元素作为数组返回。

数组必须是字符串或数字的列表。字符串基于字典排序。

  • 当前结果:["b", "a", "c"]

    表达式:sort(@)

    最终结果:["a", "b", "c"]

  • 当前结果:[1, 4, 2]

    表达式:sort(@)

    最终结果:[1, 2, 4]

sort_by

array, expression->number|expression->string

-

使用入参中的表达式作为排序键对入参的数组进行排序。对于元素数组中的每个元素,将应用入参中的表达式,并将结果值用作对元素排序时使用的键。

sort_by遵循与sort函数相同的排序逻辑。

当前结果:{"people": [{"name": "b", "age": 30, "age_str": "30"}, {"name": "a", "age": 50, "age_str": "50"}, {"name": "c", "age": 40, "age_str": "40"}]}

对于如上当前结果:

  • 表达式:sort_by(people, &age)[].age

    最终结果:[30, 40, 50]

  • 表达式:sort_by(people, &age)[0]

    最终结果:{"age": 30, "age_str": "30", "name": "b"}

  • 表达式:sort_by(people, &to_number(age_str))[1]

    最终结果:{"age": 40, "age_str": "40", "name": c}

starts_with

string, string

boolean

如果入参的两个字符串中,前者以后者开头,则返回true,否则此函数返回false。

  • 当前结果:foobarbaz

    表达式:starts_with(@, 'foo')

    最终结果:true

  • 当前结果:foobarbaz

    表达式:starts_with(@, 'baz')

    最终结果:false

  • 当前结果:foobarbaz

    表达式:starts_with(@, 'f')

    最终结果:true

sum

array[number]

number

返回所提供的数组参数的总和。

空数组将产生返回值0。

  • 当前结果:[10, 15]

    表达式:sum(@)

    最终结果:25

  • 当前结果:[]

    表达式:sum(@)

    最终结果:0

to_array

any

array

array:返回传入的值。

number|string|object|boolean:返回包含传入参数的单元素数组。

  • 表达式:to_array(`[1, 2]`)

    最终结果:[1, 2]

  • 表达式:to_array('string')

    最终结果:["string"]

  • 表达式:to_array(`0`)

    最终结果:[0]

  • 表达式:to_array(`true`)

    最终结果:[true]

  • 表达式:to_array(`{"foo": "bar"}`)

    最终结果:[{"foo": "bar"}]

to_string

any

string

string:返回传入的值。

number|array|object|boolean:对象的json编码值。

  • 表达式:to_string(`2`)

    最终结果:"2"

  • 表达式:to_string(`[]`)

    最终结果:"[]"

  • 表达式:to_string(false)

    最终结果:"null"

to_number

any

number

string:返回解析后的数字。

number:返回传入的值。

array|object|boolean|null:KooCLI会提示错误告警信息并输出原json结果

  • 表达式:to_number(`2.3`)

    最终结果:2.3

  • 表达式:to_number(`2`)

    最终结果:2

type

array|object|string|number|boolean|null

string

将给定入参的数据类型作为字符串值返回。

返回值必须是以下之一:

  • “number”
  • “string”
  • “boolean”
  • “array”
  • “object”
  • “null”
  • 表达式:type('foo')

    最终结果:“string”

  • 表达式:type(`true`)

    最终结果:“boolean”

  • 表达式:type(`null`)

    最终结果:“null”

  • 表达式:type(`123`)

    最终结果:number

  • 表达式:type(`123.05`)

    最终结果:number

  • 表达式:type(`[1,2]`)

    最终结果:“array”

  • 当前结果:{"abc": "123"}

    表达式:type(@)

    最终结果:“object”

values

object

array

返回包含所提供json对象的值的数组。由于json哈希是继承的无序的,因此与提供的入参对象关联的值是继承的无序的。实现不需要以任何特定顺序返回json对象的值的数组。

当前结果:{"a": "first", "b": "second", "c": "third"}

表达式:values(@)

最终结果可能是:

  • ["first", "second", "third"]
  • ["first", "third", "second"]
  • ["second", "first", "third"]
  • ["second", "third", "first"]
  • ["third", "first", "second"]
  • ["third", "second", "first"]