diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 185a184daa..789ca630d2 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11514,7 +11514,8 @@ table2-mapping
from the JSON data, similar to XPath expressions used
for SQL access to XML. In PostgreSQL,
path expressions are implemented as the jsonpath
- data type, described in .
+ data type and can use any elements described in
+ .
JSON query functions and operators
@@ -11561,7 +11562,7 @@ table2-mapping
},
{ "location": [ 47.706, 13.2635 ],
"start time": "2018-10-14 10:39:21",
- "HR": 130
+ "HR": 135
} ]
}
}
@@ -11613,23 +11614,33 @@ table2-mapping
When defining the path, you can also use one or more
- filter expressions, which work similar to
- the WHERE clause in SQL. Each filter expression
- can provide one or more filtering conditions that are applied
- to the result of the path evaluation. Each filter expression must
- be enclosed in parentheses and preceded by a question mark.
- Filter expressions are evaluated from left to right and can be nested.
- The @ variable denotes the current path evaluation
- result to be filtered, and can be followed by one or more accessor
- operators to define the JSON element by which to filter the result.
- Functions and operators that can be used in the filtering condition
- are listed in .
- SQL/JSON defines three-valued logic, so the result of the filter
- expression may be true, false,
+ filter expressions that work similar to the
+ WHERE clause in SQL. A filter expression begins with
+ a question mark and provides a condition in parentheses:
+
+
+? (condition)
+
+
+
+
+ Filter expressions must be specified right after the path evaluation step
+ to which they are applied. The result of this 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,
or unknown. The unknown value
- plays the same role as SQL NULL. Further path
+ plays the same role as SQL NULL and can be tested
+ for with the is unknown predicate. Further path
evaluation steps use only those items for which filter expressions
- return true.
+ return true.
+
+
+
+ Functions and operators that can be used in filter expressions are listed
+ in . The path
+ evaluation result to be filtered is denoted by the @
+ variable. To refer to a JSON element stored at a lower nesting level,
+ add one or more accessor operators after @.
@@ -11643,8 +11654,8 @@ table2-mapping
To get the start time of segments with such values instead, you have to
filter out irrelevant segments before returning the start time, so the
- filter is applied to the previous step and the path in the filtering
- condition is different:
+ filter expression is applied to the previous step, and the path used
+ in the condition is different:
'$.track.segments[*] ? (@.HR > 130)."start time"'
@@ -11669,9 +11680,9 @@ table2-mapping
- You can also nest filters within each other:
+ You can also nest filter expressions within each other:
-'$.track ? (@.segments[*] ? (@.HR > 130)).segments.size()'
+'$.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.
@@ -12261,7 +12272,7 @@ table2-mapping
@?
jsonpath
- Does JSON path returns any item for the specified JSON value?
+ Does JSON path return any item for the specified JSON value?
'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'
@@ -12289,8 +12300,8 @@ table2-mapping
The @? and @@ operators suppress
- errors including: lacking object field or array element, unexpected JSON
- item type and numeric errors.
+ the following errors: lacking object field or array element, unexpected
+ JSON item type, and numeric errors.
This behavior might be helpful while searching over JSON document
collections of varying structure.
@@ -13146,17 +13157,17 @@ table2-mapping
jsonb_path_query, jsonb_path_query_array and
jsonb_path_query_first
functions have optional vars and silent
- argument.
+ arguments.
- When vars argument is specified, it constitutes an object
- contained variables to be substituted into jsonpath
- expression.
+ If the vars argument is specified, it provides an
+ object containing named variables to be substituted into a
+ jsonpath expression.
- When silent argument is specified and has
- true value, the same errors are suppressed as it is in
- the @? and @@ operators.
+ If the silent argument is specified and has the
+ true value, these functions suppress the same errors
+ as the @? and @@ operators.
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index 2aa98024ae..0d8e2c6de4 100644
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -815,21 +815,18 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
.**{level}
- .**{lower_level to
- upper_level}
-
-
- .**{lower_level to
- last}
+ .**{start_level to
+ end_level}
- Same as .**, but with filter over nesting
- level of JSON hierarchy. Levels are specified as integers.
- Zero level corresponds to current object. This is a
- PostgreSQL extension of the SQL/JSON
- standard.
+ Same as .**, but with a filter over nesting
+ levels of JSON hierarchy. Nesting levels are specified as integers.
+ Zero level corresponds to the current object. To access the lowest
+ nesting level, you can use the last keyword.
+ This is a PostgreSQL extension of
+ the SQL/JSON standard.
@@ -841,19 +838,22 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
- Array element accessor. subscript
- might be given in two forms: expr
- or lower_expr to upper_expr.
- The first form specifies single array element by its index. The second
- form specified array slice by the range of indexes. Zero index
- corresponds to the first array element.
+ Array element accessor.
+ subscript can be
+ given in two forms: index
+ or start_index to end_index.
+ The first form returns a single array element by its index. The second
+ form returns an array slice by the range of indexes, including the
+ elements that correspond to the provided
+ start_index and end_index.
- An expression in the subscript may be an integer,
- numeric expression, or any other jsonpath expression
- returning single numeric value. The last keyword
- can be used in the expression denoting the last subscript in an array.
- That's helpful for handling arrays of unknown length.
+ The specified index can be an integer, as
+ well as an expression returning a single numeric value, which is
+ automatically cast to integer. Zero index corresponds to the first
+ array element. You can also use the last keyword
+ to denote the last array element, which is useful for handling arrays
+ of unknown length.