From 9f771868c446c44dae6b97c68eeb1b19da32c50a Mon Sep 17 00:00:00 2001 From: Alexander Korotkov Date: Fri, 13 Sep 2019 17:12:20 +0300 Subject: [PATCH] Documentation improvements to jsonpath Besides cosmetic improvements it removes statement that operators necessary need to be separated from operands with spaces, which is not really true. Discussion: https://postgr.es/m/CAEkD-mDUZrRE%3Dk-FznEg4Ed2VdjpZCyHoyo%2Bp0%2B8KvHqR%3DpNVQ%40mail.gmail.com Author: Liudmila Mantrova, Alexander Lakhin Reviewed-by: Alexander Korotkov, Alvaro Herrera Backpatch-through: 12 --- doc/src/sgml/func.sgml | 41 +++++++++++++++++++---------------------- doc/src/sgml/json.sgml | 10 +++++----- 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 0d6d883dbf..829ad07a90 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -11544,7 +11544,7 @@ table2-mapping JSON query functions and operators pass the provided path expression to the path engine - for evaluation. If the expression matches the JSON data to be queried, + for evaluation. If the expression matches the queried JSON data, the corresponding SQL/JSON item is returned. Path expressions are written in the SQL/JSON path language and can also include arithmetic expressions and functions. @@ -11604,7 +11604,7 @@ table2-mapping If the item to retrieve is an element of an array, you have - to unnest this array using the [*] operator. For example, + to unnest this array using the [*] operator. For example, the following path will return location coordinates for all the available track segments: @@ -11625,8 +11625,7 @@ table2-mapping The result of each path evaluation step can be processed by one or more jsonpath operators and methods listed in . - Each method must be preceded by a dot, while arithmetic and Boolean - operators are separated from the operands by spaces. For example, + Each method name must be preceded by a dot. For example, you can get an array size: '$.track.segments.size()' @@ -11907,7 +11906,7 @@ table2-mapping double() - Approximate numeric value converted from a string + Approximate floating-point number converted from an SQL/JSON number or a string {"len": "1.9"} $.len.double() * 2 3.8 @@ -11936,10 +11935,10 @@ table2-mapping keyvalue() - Sequence of object's key-value pairs represented as array of objects + Sequence of object's key-value pairs represented as array of items containing three fields ("key", "value", and "id"). - "id" is an unique identifier of the object + "id" is a unique identifier of the object key-value pair belongs to. {"x": "20", "y": 32} @@ -12061,9 +12060,9 @@ table2-mapping like_regex Tests pattern matching with POSIX regular expressions - (). Supported flags + (see ). Supported flags are i, s, m, - x and q. + x, and q. ["abc", "abd", "aBdC", "abdacb", "babc"] $[*] ? (@ like_regex "^ab.*c" flag "i") "abc", "aBdC", "abdacb" @@ -12077,7 +12076,7 @@ table2-mapping exists - Tests whether a path expression has at least one SQL/JSON item + Tests whether a path expression matches at least one SQL/JSON item {"x": [1, 2], "y": [2, 4]} strict $.* ? (exists (@ ? (@[*] > 2))) 2, 4 @@ -12302,10 +12301,9 @@ table2-mapping @@ jsonpath - JSON path predicate check result for the specified JSON value. - Only first result item is taken into account. If there are no results - or the first result item is not Boolean, then null - is returned. + Returns the result of 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. '{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2' @@ -12943,7 +12941,7 @@ table2-mapping - jsonb_path_exists(target jsonb, path jsonpath [, vars jsonb, silent bool]) + jsonb_path_exists(target jsonb, path jsonpath [, vars jsonb [, silent bool]]) boolean @@ -12968,10 +12966,9 @@ table2-mapping boolean - Returns JSON path predicate result for the specified JSON value. - Only first result item is taken into account. If there are no results - or the first result item is not Boolean, then null - is returned. + Returns the result of 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. @@ -13178,18 +13175,18 @@ table2-mapping The jsonb_path_exists, jsonb_path_match, - jsonb_path_query, jsonb_path_query_array and + jsonb_path_query, jsonb_path_query_array, and jsonb_path_query_first functions have optional vars and silent arguments. - If the vars argument is specified, it provides an + If the vars argument is specified, it provides an object containing named variables to be substituted into a jsonpath expression. - If the silent argument is specified and has the + 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 2d2f404b73..4f566a4c8d 100644 --- a/doc/src/sgml/json.sgml +++ b/doc/src/sgml/json.sgml @@ -490,11 +490,11 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"'; SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] ? (@ == "qui")'; GIN index extracts statements of following form out of - jsonpath: accessors_chain = const. + jsonpath: accessors_chain = const. Accessors chain may consist of .key, - [*] and [index] accessors. + [*], and [index] accessors. jsonb_ops additionally supports .* - and .** statements. + and .** accessors. Another approach to querying is to exploit containment, for example: @@ -650,12 +650,12 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu - Dot . is used for member access. + Dot (.) is used for member access. - Square brackets [] are used for array access. + Square brackets ([]) are used for array access.