From 5a7d697a39365d9762afa8e618bcbdcf592966fa Mon Sep 17 00:00:00 2001 From: Alexander Korotkov Date: Wed, 10 Jul 2019 07:46:16 +0300 Subject: [PATCH] Assorted fixes for jsonpath documentation This commit contains assorted fixes for jsonpath documentation including: grammar fixes, incorrect examples fixes as well as wording improvements. Discussion: https://postgr.es/m/CAA-aLv4VVX%3Db9RK5hkfPXJczqaiTdqO04teW9i0wiQVhdKcqzw%40mail.gmail.com Author: Liudmila Mantrova Reviewed-by: Alexander Korotkov Reported-by: Thom Brown --- doc/src/sgml/func.sgml | 73 ++++++++++++++++++++++++------------------ doc/src/sgml/json.sgml | 44 ++++++++++++------------- 2 files changed, 64 insertions(+), 53 deletions(-) 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. -- 2.40.0