From 4387c338bfe446b9a894f38b79fb82e816960c39 Mon Sep 17 00:00:00 2001 From: Amit Langote Date: Mon, 20 May 2024 20:04:49 +0900 Subject: [PATCH v1] SQL/JSON: Various fixes to SQL/JSON query function docs 1. Remove the keyword SELECT from the examples to be consistent with the examples of other JSON-related functions listed on the same page. 2. Add tags around the function's syntax definition. 3. Capitalize function names in the syntax synopsis and the examples. 4. Remove unnecessary tags from the functions' description text to combine it into one paragraph. While at it, rewrite the sentence about the RETURNING clause in JSON_QUERY() and JSON_VALUE()'s description to clarify that coercion may occur if needed. Suggested-by: Thom Brown Reviewed-by: Jian He Discussion: https://postgr.es/m/CAA-aLv7Dfy9BMrhUZ1skcg=OdqysWKzObS7XiDXdotJNF0E44Q@mail.gmail.com --- doc/src/sgml/func.sgml | 81 +++++++++++++++++++++++------------------- 1 file changed, 45 insertions(+), 36 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index 2609269610..f9456ee880 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -18691,9 +18691,12 @@ $.* ? (@ like_regex "^\\d+$") json_exists - json_exists ( - context_item, path_expression PASSING { value AS varname } , ... - { TRUE | FALSE | UNKNOWN | ERROR } ON ERROR ) + +JSON_EXISTS ( +context_item, path_expression + PASSING { value AS varname } , ... +{ TRUE | FALSE | UNKNOWN | ERROR } ON ERROR ) boolean + Returns true if the SQL/JSON path_expression @@ -18713,15 +18716,15 @@ $.* ? (@ like_regex "^\\d+$") Examples: - select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)') + JSON_EXISTS(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)') t - select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR) + JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR) f - select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR) + JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR) ERROR: jsonpath array subscript is out of bounds @@ -18731,13 +18734,16 @@ ERROR: jsonpath array subscript is out of bounds json_query - json_query ( - context_item, path_expression PASSING { value AS varname } , ... - RETURNING data_type FORMAT JSON ENCODING UTF8 - { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAY WRAPPER - { KEEP | OMIT } QUOTES ON SCALAR STRING - { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON EMPTY - { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON ERROR ) + +JSON_QUERY ( +context_item, path_expression + PASSING { value AS varname } , ... + RETURNING data_type FORMAT JSON ENCODING UTF8 + { WITHOUT | WITH { CONDITIONAL | UNCONDITIONAL } } ARRAY WRAPPER + { KEEP | OMIT } QUOTES ON SCALAR STRING + { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON EMPTY + { ERROR | NULL | EMPTY { ARRAY | OBJECT } | DEFAULT expression } ON ERROR ) jsonb + Returns the result of applying the SQL/JSON @@ -18746,6 +18752,7 @@ ERROR: jsonpath array subscript is out of bounds PASSING values. + Returns the result of applying the SQL/JSON If the path expression returns multiple SQL/JSON items, it might be necessary to wrap the result using the WITH WRAPPER clause to make it a valid JSON string. If the wrapper is @@ -18765,8 +18772,8 @@ ERROR: jsonpath array subscript is out of bounds The RETURNING clause can be used to specify the - data_type of the result value. By default, - the returned value will be of type jsonb. + data_type to coerce the result value to, + which is of type jsonb by default. The ON EMPTY clause specifies the behavior if @@ -18777,9 +18784,9 @@ ERROR: jsonpath array subscript is out of bounds The ON ERROR clause specifies the behavior if an error occurs when evaluating - path_expression, including the operation to - coerce the result value to the output type, or during the execution of - ON EMPTY behavior (that is caused by empty result + path_expression, when coercing the result + value to the RETURNING type, or during the execution + of ON EMPTY behavior (that is caused by empty result of path_expression evaluation). The default when ON ERROR is not specified is to return a null value. @@ -18788,15 +18795,15 @@ ERROR: jsonpath array subscript is out of bounds Examples: - select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER) + JSON_QUERY(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER) [3] - select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES); + JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES); [1, 2] - select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR); + JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR); ERROR: malformed array literal: "[1, 2]" @@ -18808,12 +18815,14 @@ DETAIL: Missing "]" after array dimensions. json_value - json_value ( - context_item, path_expression - PASSING { value AS varname } , ... - RETURNING data_type - { ERROR | NULL | DEFAULT expression } ON EMPTY - { ERROR | NULL | DEFAULT expression } ON ERROR ) + +JSON_VALUE ( +context_item, path_expression + PASSING { value AS varname } , ... + RETURNING data_type + { ERROR | NULL | DEFAULT expression } ON EMPTY + { ERROR | NULL | DEFAULT expression } ON ERROR ) text + Returns the result of applying the SQL/JSON @@ -18825,36 +18834,36 @@ DETAIL: Missing "]" after array dimensions. The extracted value must be a single SQL/JSON scalar item; an error is thrown if that's not the case. If you expect that extracted value might be an object or an array, use the - json_query function instead. + JSON_QUERY function instead. The RETURNING clause can be used to specify the - data_type of the result value. By default, - the returned value will be of type text. + data_type to coerce the result value to, + which is of type text by default. The ON ERROR and ON EMPTY clauses have similar semantics as mentioned in the description of - json_query. + JSON_QUERY. - Note that scalar strings returned by json_value + Note that scalar strings returned by JSON_VALUE always have their quotes removed, equivalent to specifying - OMIT QUOTES in json_query. + OMIT QUOTES in JSON_QUERY. Examples: - select json_value(jsonb '"123.45"', '$' RETURNING float) + JSON_VALUE(jsonb '"123.45"', '$' RETURNING float) 123.45 - select json_value(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI YYYY-MM-DD")' RETURNING date) + JSON_VALUE(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI YYYY-MM-DD")' RETURNING date) 2015-02-01 - select json_value(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR) + JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR) 9 -- 2.43.0