Does JSON path return any item for the specified JSON value?
+ (This is useful only with SQL-standard JSON path expressions, not
+ predicate check
+ expressions, since those always return a value.)
'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'
Returns the result of a JSON path predicate check for the
- specified JSON value. Only the first item of the result is taken into
- account. If the result is not Boolean, then NULL
- is returned.
+ specified JSON value.
+ (This is useful only
+ with predicate
+ check expressions, not SQL-standard JSON path expressions,
+ since it will return NULL if the path result is
+ not a single boolean value.)
'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'
Checks whether the JSON path returns any item for the specified JSON
value.
+ (This is useful only with SQL-standard JSON path expressions, not
+ predicate check
+ expressions, since those always return a value.)
If the
vars argument is specified, it must
be a JSON object, and its fields provide named values to be
substituted into the jsonpath expression.
Returns the result of a JSON path predicate check for the specified
- JSON value. Only the first item of the result is taken into account.
- If the result is not Boolean, then NULL is returned.
+ JSON value.
+ (This is useful only
+ with predicate
+ check expressions, not SQL-standard JSON path expressions,
+ since it will either fail or return NULL if the
+ path result is not a single boolean value.)
and
silent arguments act the same as
for jsonb_path_exists.
Returns all JSON items returned by the JSON path for the specified
JSON value.
+ For SQL-standard JSON path expressions it returns the JSON
+ values selected from
target.
+ For predicate
+ check expressions it returns the result of the predicate
+ check: true, false,
+ or null.
and
silent arguments act the same as
for jsonb_path_exists.
Returns all JSON items returned by the JSON path for the specified
JSON value, as a JSON array.
- and
silent arguments act the same as
- for jsonb_path_exists.
+ The parameters are the same as
+ for jsonb_path_query.
jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
Returns the first JSON item returned by the JSON path for the
- specified JSON value. Returns NULL if there are no
+ specified JSON value, or NULL if there are no
results.
- and
silent arguments act the same as
- for jsonb_path_exists.
+ The parameters are the same as
+ for jsonb_path_query.
jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min && @ <= $max)', '{"min":2, "max":4}')
- SQL/JSON path expressions specify the items to be retrieved
- from the JSON data, similar to XPath expressions used
- for
SQL access to XML. In
PostgreSQL,
+ SQL/JSON path expressions specify item(s) to be retrieved
+ from a JSON value, similarly to XPath expressions used
+ for
access to XML content. In
PostgreSQL,
path expressions are implemented as the jsonpath
data type and can use any elements described in
.
pass the provided path expression to the path engine
for evaluation. If the expression matches the queried JSON data,
the corresponding JSON item, or set of items, is returned.
+ If there is no match, the result will be NULL,
+ false, or an error, depending on the function.
Path expressions are written in the SQL/JSON path language
and can include arithmetic expressions and functions.
To refer to the JSON value being queried (the
context item), use the $ variable
- in the path expression. It can be followed by one or more
+ in the path expression. The first element of a path must always
+ be $. It can be followed by one or more
accessor operators,
which go down the JSON structure level by level to retrieve sub-items
- of the context item. Each operator that follows deals with the
- result of the previous evaluation step.
+ of the context item. Each accessor operator acts on the
+ result(s) of the previous evaluation step, producing zero, one, or more
+ output items from each input item.
For example, suppose you have some JSON data from a GPS tracker that you
would like to parse, such as:
-{
+SELECT '{
"track": {
"segments": [
{
}
]
}
-}
+}' AS json \gset
+ (The above example can be copied-and-pasted
+ into
psql to set things up for the following
+ examples. Then
psql will
+ expand :'json' into a suitably-quoted string
+ constant containing the JSON value.)
To retrieve the available track segments, you need to use the
.key accessor
- operator to descend through surrounding JSON objects:
-$.track.segments
-
+ operator to descend through surrounding JSON objects, for example:
+
+
=> select jsonb_path_query(:'json', '$.track.segments');+ jsonb_path_query
+-----------------------------------------------------------&zwsp;-----------------------------------------------------------&zwsp;---------------------------------------------
+ [{"HR": 73, "location": [47.763, 13.4034], "start time": "2018-10-14 10:05:14"}, {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}]
+
To retrieve the contents of an array, you typically use the
- [*] operator. For example,
- the following path will return the location coordinates for all
+ [*] operator.
+ The following example will return the location coordinates for all
the available track segments:
-$.track.segments[*].location
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*].location');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
+ Here we started with the whole JSON input value ($),
+ then the .track accessor selected the JSON object
+ associated with the "track" object key, then
+ the .segments accessor selected the JSON array
+ associated with the "segments" key within that
+ object, then the [*] accessor selected each element
+ of that array (producing a series of items), then
+ the .location accessor selected the JSON array
+ associated with the "location" key within each of
+ those objects. In this example, each of those objects had
+ a "location" key; but if any of them did not,
+ the .location accessor would have simply produced no
+ output for that input item.
To return the coordinates of the first segment only, you can
specify the corresponding subscript in the []
accessor operator. Recall that JSON array indexes are 0-relative:
-$.track.segments[0].location
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments[0].location');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+
The result of each path evaluation step can be processed
- by one or more jsonpath operators and methods
+ by one or more of the jsonpath operators and methods
listed in .
Each method name must be preceded by a dot. For example,
you can get the size of an array:
-$.track.segments.size()
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments.size()');+ jsonb_path_query
+------------------
+ 2
+
More examples of using jsonpath operators
and methods within path expressions appear below in
.
- When defining a path, you can also use one or more
+ A path can also contain
filter expressions that work similarly to the
WHERE clause in SQL. A filter expression begins with
a question mark and provides a condition in parentheses:
-<programlisting>
+<synopsis>
? (condition)
-programlisting>
+synopsis>
Filter expressions must be written just after the path evaluation step
to which they should apply. The result of that step is filtered to include
only those items that satisfy the provided condition. SQL/JSON defines
- three-valued logic, so the condition can be true, false,
+ three-valued logic, so the condition can
+ produce true, false,
or unknown. The unknown value
plays the same role as SQL NULL and can be tested
for with the is unknown predicate. Further path
The functions and operators that can be used in filter expressions are
listed in . Within a
filter expression, the @ variable denotes the value
- being filtered (i.e., one result of the preceding path step). You can
+ being considered (i.e., one result of the preceding path step). You can
write accessor operators after @ to retrieve component
items.
For example, suppose you would like to retrieve all heart rate values higher
- than 130. You can achieve this using the following expression:
-$.track.segments[*].HR ? (@ > 130)
-
+ than 130. You can achieve this as follows:
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*].HR ? (@ > 130)');+ jsonb_path_query
+------------------
+ 135
+
To get the start times of segments with such values, you have to
- filter out irrelevant segments before returning the start times, so the
+ filter out irrelevant segments before selecting the start times, so the
filter expression is applied to the previous step, and the path used
in the condition is different:
-$.track.segments[*] ? (@.HR > 130)."start time"
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*] ? (@.HR > 130)."start time"');+ jsonb_path_query
+-----------------------
+ "2018-10-14 10:39:21"
+
- You can use several filter expressions in sequence, if required. For
- example, the following expression selects start times of all segments that
+ You can use several filter expressions in sequence, if required.
+ The following example selects start times of all segments that
contain locations with relevant coordinates and high heart rate values:
-$.track.segments[*] ? (@.location[1] < 13.4) ? (@.HR > 130)."start time"
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4) ? (@.HR > 130)."start time"');+ jsonb_path_query
+-----------------------
+ "2018-10-14 10:39:21"
+
Using filter expressions at different nesting levels is also allowed.
The following example first filters all segments by location, and then
returns high heart rate values for these segments, if available:
-$.track.segments[*] ? (@.location[1] < 13.4).HR ? (@ > 130)
-
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] < 13.4).HR ? (@ > 130)');+ jsonb_path_query
+------------------
+ 135
+
- You can also nest filter expressions within each other:
-$.track ? (exists(@.segments[*] ? (@.HR > 130))).segments.size()
-
- This expression returns the size of the track if it contains any
- segments with high heart rate values, or an empty sequence otherwise.
+ You can also nest filter expressions within each other.
+ This example returns the size of the track if it contains any
+ segments with high heart rate values, or an empty sequence otherwise:
+
+
=> select jsonb_path_query(:'json', '$.track ? (exists(@.segments[*] ? (@.HR > 130))).segments.size()');+ jsonb_path_query
+------------------
+ 2
+
-
PostgreSQL's implementation of the SQL/JSON path
- language has the following deviations from the SQL/JSON standard:
-
+
+
Deviations from the SQL Standard
+
PostgreSQL's implementation of the SQL/JSON path
+ language has the following deviations from the SQL/JSON standard.
+
- >
- <listitem>
+ >
+ <title>Boolean Predicate Check Expressions>
- A path expression can be a Boolean predicate, although the SQL/JSON
- standard allows predicates only in filters. This is necessary for
- implementation of the @@ operator. For example,
- the following jsonpath expression is valid in
-$.track.segments[*].HR < 70
-
-
-
+ As an extension to the SQL standard,
+ a
PostgreSQL path expression can be a
+ Boolean predicate, whereas the SQL standard allows predicates only within
+ filters. While SQL-standard path expressions return the relevant
+ element(s) of the queried JSON value, predicate check expressions
+ return the single three-valued result of the
+ predicate: true,
+ false, or unknown.
+ For example, we could write this SQL-standard filter expression:
+
+
=> select jsonb_path_query(:'json', '$.track.segments ?(@[*].HR > 130)');+ jsonb_path_query
+-----------------------------------------------------------&zwsp;----------------------
+ {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}
+
+ The similar predicate check expression simply
+ returns true, indicating that a match exists:
+
+
=> select jsonb_path_query(:'json', '$.track.segments[*].HR > 130');+ jsonb_path_query
+------------------
+ true
+
+
-
- There are minor differences in the interpretation of regular
- expression patterns used in like_regex filters, as
- described in .
-
-
-
+
+ Predicate check expressions are required in the
+ @@ operator (and the
+ jsonb_path_match function), and should not be used
+ with the @? operator (or the
+ jsonb_path_exists function).
+
+
+
-
+
+
Regular Expression Interpretation
+ There are minor differences in the interpretation of regular
+ expression patterns used in like_regex filters, as
+ described in .
+
+
+
+
+
Strict and Lax Modes
When you query JSON data, the path expression may not match the
actual JSON data structure. An attempt to access a non-existent
- member of an object or element of an array results in a
+ member of an object or element of an array is defined as a
structural error. SQL/JSON path expressions have two modes
of handling structural errors:
lax (default) — the path engine implicitly adapts
the queried data to the specified path.
- Any remaining structural errors are suppressed and converted
- to empty SQL/JSON sequences.
+ Any structural errors that cannot be fixed as described below
+ are suppressed, producing no match.
- The lax mode facilitates matching of a JSON document structure and path
- expression if the JSON data does not conform to the expected schema.
+ Lax mode facilitates matching of a JSON document and path
+ expression when the JSON data does not conform to the expected schema.
If an operand does not match the requirements of a particular operation,
- it can be automatically wrapped as an SQL/JSON array or unwrapped by
+ it can be automatically wrapped as an SQL/JSON array, or unwrapped by
converting its elements into an SQL/JSON sequence before performing
- this operation. Besides, comparison operators automatically unwrap their
- operands in the lax mode, so you can compare SQL/JSON arrays
+ the operation. Also, comparison operators automatically unwrap their
+ operands in lax mode, so you can compare SQL/JSON arrays
out-of-the-box. An array of size 1 is considered equal to its sole element.
- Automatic unwrapping is not performed only when:
+ Automatic unwrapping is not performed when:
For example, when querying the GPS data listed above, you can
abstract from the fact that it stores an array of segments
- when using the lax mode:
-lax $.track.segments.location
-
+ when using lax mode:
+
+
=> select jsonb_path_query(:'json', 'lax $.track.segments.location');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
- In the strict mode, the specified path must exactly match the structure of
- the queried JSON document to return an SQL/JSON item, so using this
- path expression will cause an error. To get the same result as in
- the lax mode, you have to explicitly unwrap the
+ In strict mode, the specified path must exactly match the structure of
+ the queried JSON document, so using this path
+ expression will cause an error:
+
+
=> select jsonb_path_query(:'json', 'strict $.track.segments.location');+ERROR: jsonpath member accessor can only be applied to an object
+
+ To get the same result as in lax mode, you have to explicitly unwrap the
segments array:
-strict $.track.segments[*].location
-
+
+
=> select jsonb_path_query(:'json', 'strict $.track.segments[*].location');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+
- The .** accessor can lead to surprising results
- when using the lax mode. For instance, the following query selects every
- HR value twice:
-lax $.**.HR
-
+ The unwrapping behavior of lax mode can lead to surprising results. For
+ instance, the following query using the .** accessor
+ selects every HR value twice:
+
+
=> select jsonb_path_query(:'json', 'lax $.**.HR');+ jsonb_path_query
+ ------------------
+ 73
+ 135
+ 73
+ 135
+
This happens because the .** accessor selects both
the segments array and each of its elements, while
the .HR accessor automatically unwraps arrays when
- using the lax mode. To avoid surprising results, we recommend using
- the .** accessor only in the strict mode. The
+ using lax mode. To avoid surprising results, we recommend using
+ the .** accessor only in strict mode. The
following query selects each HR value just once:
-strict $.**.HR
-
+
+
=> select jsonb_path_query(:'json', 'strict $.**.HR');+ jsonb_path_query
+ ------------------
+ 73
+ 135
+
+ The unwrapping of arrays can also lead to unexpected results. Consider this
+ example, which selects all the location arrays:
+
+
=> select jsonb_path_query(:'json', 'lax $.track.segments[*].location');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+(2 rows)
+
+ As expected it returns the full arrays. But applying a filter expression
+ causes the arrays to be unwrapped to evaluate each item, returning only the
+ items that match the expression:
+
+
=> select jsonb_path_query(:'json', 'lax $.track.segments[*].location ?(@[*] > 15)');+ jsonb_path_query
+------------------
+ 47.763
+ 47.706
+(2 rows)
+
+ This despite the fact that the full arrays are selected by the path
+ expression. Use strict mode to restore selecting the arrays:
+
+
=> select jsonb_path_query(:'json', 'strict $.track.segments[*].location ?(@[*] > 15)');+ jsonb_path_query
+-------------------
+ [47.763, 13.4034]
+ [47.706, 13.2635]
+(2 rows)
+
+
projects / postgresql.git / commitdiff