Table of Contents
- 13 Supported JSONPath functionality
- Overview
- Supported segments
- Filter expression
- Functions
- Output value
- Whitespace
- Strings
- Examples
- Input data
The full JSONPath functionality as described in this page is available starting with Zabbix 4.2.5.
See Also
Creating a Custom Mapping FileJSON PointerFortux | JSONPath StandardJSON path syntax in detailOverview
JSONPath consists of segments separated with dots. A segment can be either a simple word like a JSON value name, * or a more complex construct enclosed within square brackets [ ]. The separating dot before bracket segment is optional and can be omitted. For example:
| Path | Description |
|---|---|
$.object.name | Return the object.name contents. |
$.object['name'] | Return the object.name contents. |
$.object.['name'] | Return the object.name contents. |
$["object"]['name'] | Return the object.name contents. |
$.['object'].["name"] | Return the object.name contents. |
$.object.history.length() | Return the number of object.history array elements. |
$[?(@.name == 'Object')].price.first() | Return the price field of the first object with name 'Object'. |
$[?(@.name == 'Object')].history.first().length() | Return the number of history array elements of the first object with name 'Object'. |
$[?(@.price > 10)].length() | Return the number of objects with price being greater than 10. |
Supported segments
| Segment | Description |
|---|---|
<name> | Match object property by name. |
* | Match all object properties. |
['<name>'] | Match object property by name. |
['<name>', '<name>', ...] | Match object property by any of the listed names. |
[<index>] | Match array element by the index. |
[<number>, <number>, ...] | Match array element by any of the listed indexes. |
[*] | Match all object properties or array elements. |
[<start>:<end>] | Match array elements by the defined range: <start> - the first index to match (including). If not specified matches all array elements from the beginning. If negative specifies starting offset from the end of array. <end> - the last index to match (excluding). If not specified matches all array elements to the end. If negative specifies starting offset from the end of array. |
[?(<expression>)] | Match objects/array elements by applying filter expression. |
To find a matching segment ignoring its ancestry (detached segment) it must be prefixed with '..' , for example $..name or $..['name'] return values of all 'name' properties.
Filter expression
Filter expression is a arithmetical expression in infix notation.
Supported operands:
| Operand | Description | Example |
|---|---|---|
"<text>"'<text>' | Text constant. | 'value: \'1\'' "value: '1'" |
<number> | Numeric constant supporting scientific notation. | 123 |
<jsonpath starting with $> | Value referred to by the JSONPath from the input document root node; only definite paths are supported. | $.object.name |
<jsonpath starting with @> | Value referred to by the JSONPath from the current object/element; only definite paths are supported. | @.name |
Supported operators:
| Operator | Type | Description | Result |
|---|---|---|---|
- | binary | Subtraction. | Number. |
+ | binary | Addition. | Number. |
/ | binary | Division. | Number. |
* | binary | Multiplication. | Number. |
== | binary | Is equal to. | Boolean (1 or 0). |
!= | binary | Is not equal to. | Boolean (1 or 0). |
< | binary | Is less than. | Boolean (1 or 0). |
<= | binary | Is less than or equal to. | Boolean (1 or 0). |
> | binary | Is greater than. | Boolean (1 or 0). |
>= | binary | Is greater than or equal to. | Boolean (1 or 0). |
=~ | binary | Matches regular expression. | Boolean (1 or 0). |
! | unary | Boolean not. | Boolean (1 or 0). |
\|\| | binary | Boolean or. | Boolean (1 or 0). |
&& | binary | Boolean and. | Boolean (1 or 0). |
Functions
Functions can be used at the end of JSONPath. Multiple functions can be chained if the preceding function returns value that is accepted by the following function.
Supported functions:
| Function | Description | Input | Output |
|---|---|---|---|
avg | Average value of numbers in input array. | Array of numbers. | Number. |
min | Minimum value of numbers in input array. | Array of numbers. | Number. |
max | Maximum value of numbers in input array. | Array of numbers. | Number. |
sum | Sum of numbers in input array. | Array of numbers. | Number. |
length | Number of elements in input array. | Array. | Number. |
first | The first array element. | Array. | A JSON construct (object, array, value) depending on input array contents. |
Quoted numeric values are accepted by the JSONPath aggregate functions since Zabbix 4.2.8. It means that the values are converted from string type to numeric if aggregation is required.
Incompatible input will cause the function to generate error.
Output value
JSONPaths can be divided in definite and indefinite paths. A definite path can return only null or a single match. An indefinite path can return multiple matches, basically JSONPaths with detached, multiple name/index list, array slice or expression segments. However, when a function is used the JSONPath becomes definite, as functions always output single value.
A definite path returns the object/array/value it's referencing, while indefinite path returns an array of the matched objects/arrays/values.
Whitespace
Whitespace (space, tab characters) can be freely used in bracket notation segments and expressions, for example, $[ 'a' ][ 0 ][ ?( $.b == 'c' ) ][ : -1 ].first( ).
Strings
Strings should be enclosed with single ' or double " quotes. Inside the strings, single or double quotes (depending on which are used to enclose it) and backslashes \ are escaped with the backslash \ character.
Examples
Input data
{ "books": [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95, "id": 1 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99, "id": 2 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99, "id": 3 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99, "id": 4 } ], "services": { "delivery": { "servicegroup": 1000, "description": "Next day delivery in local town", "active": true, "price": 5 }, "bookbinding": { "servicegroup": 1001, "description": "Printing and assembling book in A5 format", "active": true, "price": 154.99 }, "restoration": { "servicegroup": 1002, "description": "Various restoration methods", "active": false, "methods": [ { "description": "Checmical cleaning", "price": 46 }, { "description": "Pressing pages damaged by moisture", "price": 24.5 }, { "description": "Rebinding torn book", "price": 99.49 } ] } }, "filters": { "price": 10, "category": "fiction", "no filters": "no \"filters\"" }, "closed message": "Store is closed", "tags": [ "a", "b", "c", "d", "e" ] }| JSONPath | Type | Result | Comments |
|---|---|---|---|
$.filters.price | definite | 10 | |
$.filters.category | definite | fiction | |
$.filters['no filters'] | definite | no "filters" | |
$.filters | definite | { "price": 10, "category": "fiction", "no filters": "no \"filters\"" } | |
$.books[1].title | definite | Sword of Honour | |
$.books[-1].author | definite | J. R. R. Tolkien | |
$.books.length() | definite | 4 | |
$.tags[:] | indefinite | ["a", "b", "c", "d", "e" ] | |
$.tags[2:] | indefinite | ["c", "d", "e" ] | |
$.tags[:3] | indefinite | ["a", "b", "c"] | |
$.tags[1:4] | indefinite | ["b", "c", "d"] | |
$.tags[-2:] | indefinite | ["d", "e"] | |
$.tags[:-3] | indefinite | ["a", "b"] | |
$.tags[:-3].length() | definite | 2 | |
$.books[0, 2].title | indefinite | ["Sayings of the Century", "Moby Dick"] | |
$.books[1]['author', "title"] | indefinite | ["Evelyn Waugh", "Sword of Honour"] | |
$..id | indefinite | [1, 2, 3, 4] | |
$.services..price | indefinite | [5, 154.99, 46, 24.5, 99.49] | |
$.books[?(@.id == 4 - 0.4 * 5)].title | indefinite | ["Sword of Honour"] | This query shows that arithmetical operations can be used in queries. Of course this query can be simplified to $.books[?(@.id == 2)].title |
$.books[?(@.id == 2 \|\| @.id == 4)].title | indefinite | ["Sword of Honour", "The Lord of the Rings"] | |
$.books[?(!(@.id == 2))].title | indefinite | ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"] | |
$.books[?(@.id != 2)].title | indefinite | ["Sayings of the Century", "Moby Dick", "The Lord of the Rings"] | |
$.books[?(@.title =~ " of ")].title | indefinite | ["Sayings of the Century", "Sword of Honour", "The Lord of the Rings"] | |
$.books[?(@.price > 12.99)].title | indefinite | ["The Lord of the Rings"] | |
$.books[?(@.author > "Herman Melville")].title | indefinite | ["Sayings of the Century", "The Lord of the Rings"] | |
$.books[?(@.price > $.filters.price)].title | indefinite | ["Sword of Honour", "The Lord of the Rings"] | |
$.books[?(@.category == $.filters.category)].title | indefinite | ["Sword of Honour","Moby Dick","The Lord of the Rings"] | |
$..[?(@.id)] | indefinite | [ { "category": "reference", "author": "Nigel Rees", "title": "Sayings of the Century", "price": 8.95, "id": 1 }, { "category": "fiction", "author": "Evelyn Waugh", "title": "Sword of Honour", "price": 12.99, "id": 2 }, { "category": "fiction", "author": "Herman Melville", "title": "Moby Dick", "isbn": "0-553-21311-3", "price": 8.99, "id": 3 }, { "category": "fiction", "author": "J. R. R. Tolkien", "title": "The Lord of the Rings", "isbn": "0-395-19395-8", "price": 22.99, "id": 4 } ] | |
$.services..[?(@.price > 50)].description | indefinite | '["Printing and assembling book in A5 format", "Rebinding torn book"] | |
$..id.length() | definite | 4 | |
$.books[?(@.id == 2)].title.first() | definite | Sword of Honour | |
$..tags.first().length() | definite | 5 | $..tags is indefinite path, so it returns an array of matched elements - [["a", "b", "c", "d", "e" ]], first() returns the first element - ["a", "b", "c", "d", "e" ] and finally length() calculates its length - 5. |
$.books[*].price.min() | definite | 8.95 | |
$..price.max() | definite | 154.99 | |
$.books[?(@.category == "fiction")].price.avg() | definite | 14.99 | |
$.books[?(@.category == $.filters.xyz)].title | indefinite | A query without match returns NULL for definite and indefinite paths. | |
$.services[?(@.active=="true")].servicegroup | indefinite | [1000,1001] | Text constants must be used in boolean value comparisons. |
$.services[?(@.active=="false")].servicegroup | indefinite | [1002] | Text constants must be used in boolean value comparisons. |
