JPath
JPath is a language for querying and manipulating JSON elements. You can use JPath to compute values, such as strings, numbers, and boolean values, from JSON elements.
Basic Selection
Select elements by using a forward slash (/). Select array items by using square brackets ( [ ] ).
The following table shows examples of basic selection of JSON elements.
Example |
Description |
State |
Expression |
Result |
|---|---|---|---|---|
|
Primitive |
Selects a JSON primitive. |
{
"object": { "attr1": "value1", "attr2": "value2" }
} |
/object/attr1 |
"value1" |
|
String Index |
Selects a character of a string. |
{
"object": { "attr1": "value1", "attr2": "value2" }
} |
/object/attr1[0] |
"v" |
|
Object |
Selects a JSON object. |
{
"object": { "attr1": "value1", "attr2": "value2" }
} |
/object |
{
"attr1": "value1", "attr2": "value2"
} |
|
Array |
Selects a JSON array. |
{
"array": [ "value1", "value2" ] } |
/array |
[
"value1", "value2" ] |
|
Array Index |
Selects an item of a JSON array by index. The index starts at 0. |
{
"array": [ 1.1, 2.2 ] } |
/array[1] |
2.2 |
|
Nested |
Selects an attribute of an object that is nested in an array. |
|
/array[1]/id |
456 |
|
Multiple Nested |
Selects all attributes of an object that is nested in an array. |
{
"array": [ { "id": 123 }, { "id": 456 } ]
} |
/array/id |
[
123, 456 ] |
|
Single Quoted Keys |
Selects key names by using single quotation marks. |
{
"name with spaces": { "some attribute": true,
"another attribute": false } } |
/'name
with spaces'/'some attribute' |
true |
|
Double Quoted Keys |
Selects key names by using double quotation marks. |
{
"name with spaces": { "some attribute": true,
"another attribute": false } } |
/"name
with spaces"/"some attribute" |
true |
|
Unicode Support |
Selects by using Unicode keys and values. |
{
"a͓̽t͓̽t͓̽r͓̽": "v͓̽a͓̽l͓̽u͓̽e͓̽"
} |
/"a͓̽t͓̽t͓̽r͓̽" |
"v͓̽a͓̽l͓̽u͓̽e ͓̽" |
Query
Array elements can be queried by using square brackets ( [ ] ). The query is evaluated against all of the array elements. The query can select any fields of the element for comparison and reference anything in the JSON document.
The following table shows query operators. a and b can be either a constant or a JPath construct. Basic selection, query, arithmetic, and functions are JPath constructs.
Operator |
Description |
|---|---|
a = b |
Equal |
a != b |
Not equal |
a > b |
Greater than |
a < b |
Less than |
a >= b |
Greater than or equal |
a <= b |
Less than or equal |
not a |
Negates the result of a |
exists a |
Checks if a exists as an attribute |
The following table shows examples of the query operators that you can apply to the array elements.
Example |
Description |
State |
Expression |
Result |
|---|---|---|---|---|
Equality (or Inequality) |
Queries an array for objects with an attribute equal to a value. |
{ "array": [ { "id": 1, "name": "Object 1" }, {
"id": 2, "name": "Object 2" }, { "id": 3, "name":
"Object 3" } ] } |
/array[@id = 2] |
[ { "id": 2, "name": "Object 2" }
] |
Greater than |
Queries an array of objects with attributes greater than a value. |
{ "array": [ { "id": 1, "name": "Object 1" }, {
"id": 2, "name": "Object 2" }, { "id": 3, "name":
"Object 3" } ] } |
/array[@id > 1] |
[ { "id": 2, "name": "Object 2" }, { "id": 3,
"name": "Object 3" } ] |
Primitives |
Selects primitives from an array that passes a specific query. |
{ "array": [ "value 1", "value 2", "value 3" ]
} |
/array[@ != "value 2"] |
[ "value 1", "value 3" ] |
And |
Selects with the 'and' operator. |
{ "array": [ "value 1", "value 2", "value 3" ]
} |
/array[@ != "value 2" and @ != 'value
3'] |
[ "value 1" ] |
Or |
Selects with the 'or' operator. |
{ "array": [ "value 1", "value 2", "value 3" ]
} |
/array[@ = "value 2" or @ = "value
3"] |
[ "value 2", "value 3" ] |
Parentheses |
Selects with parentheses. |
{ "array": [ "value 1", "value 2", "value 3" ]
} |
/array[not (@ = "value 2" or @ = "value
3")] |
[ "value 1" ] |
Exists |
Selects objects of an array that have a specific attribute. |
{ "array": [ { "id": 1, "name": "Object 1" }, {
"id": 2, "name": "Object 2" }, { "id": 3, } ]
} |
/array[exists @name] |
[ { "id": 1, "name": "Object 1" }, { "id": 2,
"name": "Object 2" } ] |
Arithmetic Operations in JSON Elements
Some basic arithmetic operations can be applied to the JSON elements.
The following table shows arithmetic operators. a and b can be either a constant or a JPath construct. Basic selection, query, arithmetic, and functions are JPath constructs.
Operator |
Description |
|---|---|
|
a + b |
Add |
|
a - b |
Subtract |
|
a * b |
Multiply |
|
a / b |
Divide |
|
a % b |
Modulo |
The following table shows examples of the arithmetic operations that you can apply to JSON elements.
Example |
Description |
State |
Expression |
Result |
|---|---|---|---|---|
Addition |
Basic addition |
{ "attr1": 1, "attr2": 4 } |
/attr1 + /attr2 |
5 |
Subtraction |
Basic subtraction |
{ "attr1": 1, "attr2": 4 } |
/attr1 - /attr2 |
-3 |
Multiplication |
Basic multiplication |
{ "attr1": 2, "attr2": 4 } |
/attr1 * /attr2 |
8 |
Division |
Basic division |
{ "attr1": 12, "attr2": 4 } |
/attr1 / /attr2 |
3 |
Parentheses |
Arithmetic that uses parentheses. |
{ "attr1": 4, "attr2": 2 } |
(/attr1 - /attr2) * (/attr1 + /
attr2) |
12 |
Arithmetic as Array Index |
Uses arithmetic to compute an array index. |
{ "attr1": 4, "attr2": 2, "array": [ "value 1",
"value 2", "value 3", ] } |
/array[/attr1 - / attr2] |
"value 3" |
Arithmetic in Query |
Uses arithmetic as part of a query. |
{ "attr1": 4, "attr2": 2, "array": [ { "id": 1,
"name": "Object 1" }, { "id": 2, "name": "Object
2" }, { "id": 3, "name": "Object 3" } ]
} |
/array[@id != (/ attr1 -
/attr2)] |
[ { "id": 1, "name": "Object 1" }, { "id": 3,
"name": "Object 3" } ] |
Functions in JPath Expressions
Some basic functions can be used in JPath expressions, such as using a function as part of a query.
The following table shows the basic functions that can be used in JPath expressions.
Function |
Description |
|---|---|
|
count(path) |
Returns the number of items at a specific path expression.
|
|
base64_encode(expr) |
Returns the base64 encoded value of a specific expression. |
|
base64_decode(expr) |
Returns the base64 decoded value of a specific expression. |
|
url_encode(expr) |
Returns the url encoded value of a specific expression. |
|
url_decode(expr) |
Returns the url decoded value of a specific expression. |
|
min(path) |
Returns the minimum value from an array at a specific path expression. |
|
max(path) |
Returns the maximum value from an array at a specific path expression. |
|
time() |
Returns time in milliseconds since epoch. |
|
trunc(expr) |
Returns the truncated value of a specific number expression. |
|
round(expr) |
Returns the rounded value of a specific number expression. |
|
floor(expr) |
Returns the floor of a specific number expression. |
|
ceil(expr) |
Returns the ceiling of a specific number expression. |
|
random_number() |
Returns a random floating point number between 0.0 and 1.0. |
|
substring(expr, begin, end) |
Returns the substring of a specific expression. |
|
left(expr, length) |
Returns the left portion of a specific expression. |
|
right(expr, length) |
Returns the right portion of a specific expression. |
|
upper(expr) |
Returns the uppercase value of a specific expression. |
|
lower(expr) |
Returns the lowercase value of a specific expression. |
|
random_string(length) |
Returns a random string of Latin alphabetic characters (a-z, A-Z). |
|
empty(path) |
Returns true if the value at a specific path expression is empty. |
|
pad_left(expr, length, padValue) |
Returns the left-padded value of a specific expression. |
|
pad_right(expr, length, padValue) |
Returns the right-padded value of a specific expression. |
|
range(begin, end) |
Returns a range of numbers as an array. |
|
keys(path) |
Returns the keys of the object at a specific path expression. |
|
values(path) |
Returns the values of the object at a specific path expression. |
|
entries(path) |
Returns the entries of the object at a specific path expression. |
The following table shows examples of basic functions that can be used in JPath expressions.
Example |
Description |
State |
Expression |
Result |
|---|---|---|---|---|
Function in query |
Uses a function as part of a query. |
{ "array": [ { "id": 1, "timestamp": 1186978597
}, { "id": 2, "timestamp": 1286978597 }, { "id":
3, "timestamp": 17586978597 } ] } |
/ array[@timestamp > time()] |
[ { "id": 3, "timestamp": 17586978597 }
] |
Find an event with the biggest timestamp |
Uses the max() function in combination with a generated array of numbers. |
{ "array": [ { "id": 1, "timestamp": 1186978597
}, { "id": 2, "timestamp": 1286978597 }, { "id":
3, "timestamp": 17586978597 } ] } |
max(/array/ timestamp) |
17586978597 |