From 98a10509f3982e4ef029148599842b0a101a62b6 Mon Sep 17 00:00:00 2001 From: Amit Langote Date: Tue, 2 Jul 2024 21:36:51 +0900 Subject: [PATCH v2 2/2] Delta against David J's patch --- doc/src/sgml/func.sgml | 332 +++++++++++++++++++---------------------- 1 file changed, 155 insertions(+), 177 deletions(-) diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml index c6ee57c104..95dc98b302 100644 --- a/doc/src/sgml/func.sgml +++ b/doc/src/sgml/func.sgml @@ -18658,37 +18658,22 @@ $.* ? (@ like_regex "^\\d+$") - - SQL/JSON Query Functions + + SQL/JSON Query Functions SQL/JSON functions JSON_EXISTS(), JSON_QUERY(), and JSON_VALUE() described in can be used to query JSON documents. Each of these functions apply a path_expression (the query) to a - context_item (the document); see - for more details on what - path_expression can contain. Spoiler, - it can contain variable names, and so there is a standard, optional, - variable_definitions clause that can be used to - passing in values for those variables. - - - - The different components of the SQL/JSON query function signatures are - described following the table. Both the json_query - and json_value functions are polymorphic in their - return type, yielding the value indicated by default by able to - be overridden by adding a return_clause or - return_data_type clause respectively. - - - - The handling of errors originating from with the function - (an invalid document is detected prior to function execution) - as well as queries producing zero results, is controllable - via the on_error_* and on_error_* - clauses. + context_item (the document). Besides the + elements described in , + path_expression can also contain variables + whose values are specified using the variable_definitions + clause described below. context_item can be + a JSON document passed as a value of type json, + jsonb document, a character or an UTF8- + endoded bytea string. @@ -18711,38 +18696,40 @@ $.* ? (@ like_regex "^\\d+$") json_exists - json_exists ( + JSON_EXISTS ( context_item, path_expression - variable_definitions - on_error_boolean) + variable_definitions + on_error_boolean) boolean Returns true if the SQL/JSON path_expression + possibly referencing the variables in variable_definitions applied to the context_item yields any items. - The ON ERROR clause specifies the behavior if - an error occurs; the default is to return the boolean - FALSE value. Note that if the + The on_error_boolean clause specifies the + behavior if an error occurs; the default is to return the + boolean FALSE value. Note that if the path_expression is strict - and ON ERROR behavior is ERROR, - an error is generated if it yields no items. + and the value of on_error_boolean is + ERROR, an error is generated if + path_expression yields no items. Examples: - select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)') + SELECT 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) + SELECT 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) + SELECT JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR) ERROR: jsonpath array subscript is out of bounds @@ -18752,46 +18739,62 @@ ERROR: jsonpath array subscript is out of bounds json_query - json_query ( + JSON_QUERY ( context_item, path_expression - variable_definitions - return_clause - wrapping_clause - quoting_clause - on_empty_set - on_error_set) - { jsonb | return_data_type } + variable_definitions + returning_clause + wrapping_clause + quoting_clause + on_empty_set + on_error_set) + { jsonb | return_data_type } Returns the result of applying the SQL/JSON - path_expression to the - context_item. + path_expression possibly referencing + the variables in variable_definitions + to the context_item. - By default, the output result will wrapped in an array. - This is controlled by the wrapping_clause. Additionally, - if only a single result is expected, the return_clause and - possibly the quoting clauses, can be included to produce + By default, the output result will be wrapped in an array. + This is controlled by the wrapping_clause. + Additionally, if only a single result value is expected, the + returning_clause and possibly the + quoting_clause can be included to produce the desired value as an SQL type. + + If path_expression points to a JSON null, + JSON_QUERY returns a JSON null. + Examples: - select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER) + SELECT JSON_QUERY(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER) [3] - select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES); + SELECT 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); + SELECT JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR); ERROR: malformed array literal: "[1, 2]" DETAIL: Missing "]" after array dimensions. + + + + SELECT JSON_QUERY(jsonb 'null', '$'); + + + json_query +------------ + null +(1 row) @@ -18799,169 +18802,145 @@ DETAIL: Missing "]" after array dimensions. json_value - json_value ( + JSON_VALUE ( context_item, path_expression - variable_definitions - return_type - on_empty_value - on_error_value) + variable_definitions + return_type + on_empty_value + on_error_value) { text | return_data_type } - Returns the result of applying the SQL/JSON scalar-producing - path_expression to the - context_item and, by default, - converting it to SQL text. + Returns the result of applying the SQL/JSON + path_expression possibly referencing + the variables in variable_definitions + to the context_item. 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. + + + If path_expression points to a JSON null, + JSON_VALUE returns a SQL NULL. Examples: - select json_value(jsonb '"123.45"', '$' RETURNING float) + SELECT 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) + SELECT 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) + SELECT JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR) 9 - + + + SELECT JSON_VALUE(jsonb 'null', '$'); + + + json_query +------------ + +(1 row) + + +
+ + Elements besides context_item and + path_expression of the SQL/JSON query function + signatures are described below: + + - - context_item - - - castable_expression - - - A value expression capable of being cast to the jsonb type. - Failure during casting will result in function execution failure, regardless - of the setting for the ON ERROR clause. - - - - - path_expression - - - jsonpath_expression - - - A value expression of type jsonpath. See each function's description for - details regarding restrictions on what application of the jsonpath expression - to the context_item can produce. - - - variable_definitions + + PASSING {value AS varname} , ... + - - PASSING { - value AS varname - } - , ... - - - - If the path_expression contains JSONPath variable expression write - PASSING after the expression and then provide a comma-separated - list of values, mapped to names using the AS keyword. - - - - - return_data_type - - - data_type_identifier - - - The json_value function expects to compute a scalar JSON value. - This clause declares what SQL-scoped data type should actually be returned as the result. - The default is text, with the JSON null value being converted to an SQL null value. - You may specify jsonb or json, in which case the computed scalar result - will be returned as-is, including the JSON null value. + A comma separated list of values with names specified with the + AS clause that correspond to the jsonpath variables + mentioned in the path_expression. - return_clause + returning_clause + + RETURNING return_data_type FORMAT JSONENCODING UTF8 + - - RETURNING return_data_type - - FORMAT JSON - - ENCODING UTF8 - - - + The JSON_QUERY and JSON_VALUE + functions are polymorphic in their output type with the + returning_clause clause dictating what that + type is. - The json_query function is polymorphic in its output type with this return_clause - clause dictating what that type is. The default is jsonb in UTF8 encoding. - This is what you receive if you omit the entire clause. + For JSON_QUERY, the default is + jsonb in UTF8 encoding, which is what + you get if you omit the entire clause. The optional format and encoding + clauses may only be used if the return_data_type is an + SQL character type. - The optional format and encoding clauses may only be used if the data_type is an SQL character type. + The JSON_VALUE function expects to compute a scalar + JSON value. It is returned by default as a value of type text + or of type return_data_type if specified. + Format and encoding clauses are not allowed + for JSON_VALUE. wrapping_clause + + WITHOUT ARRAY WRAPPER + WITH UNCONDITIONAL ARRAY WRAPPER + WITH CONDITIONAL ARRAY WRAPPER + - WITHOUT ARRAY WRAPPER - WITH UNCONDITIONAL ARRAY WRAPPER - WITHCONDITIONAL ARRAY WRAPPER - - - The json_query function can produce multiple JSON values, either as an object or a set, - as a result of evaluating the path_expression. The WITHOUT - variant will simply return the result as-is, possibly resulting in a error in the set case. The default - WITH variant will always generate an outer array wrapper around the result. To - omit the wrapper if the result is already a single object or array add the CONDITIONAL - keyword after WITH. - - - The default behavior is to unconditionally wrap the result in an array. + When JSON_QUERY function produces multiple JSON + values, they are returned as a JSON array. By default, the result values + are unconditionally wrapped even if the array contains only one element. + You can specify the WITH CONDITIONAL variant to say + that the wrapper be added only when there are multiple values in the + resulting array. Or specify the WITHOUT variant to + say that the wrapper be removed when there is only one element, but it + is ignored if there are multiple values. quoting_clause + +{ KEEP | OMIT } QUOTES ON SCALAR STRING + - { KEEP | OMIT } QUOTES ON SCALAR STRING - - - The json_query function outputs jsonb values; therefore a single scalar text result - will be quoted. Specify OMIT QUOTES to remove the quotes and thus producing a result that can - be cast to text. - - - The optional ON SCALAR STRING modifier represents the default behavior. + The JSON_QUERY function outputs jsonb + values; therefore a single scalar text result will be quoted by default. + You can specify OMIT QUOTES to remove the quotes. - To ensure the construction of a valid JSON array the combination of omit quotes and producing an - unconditional wrapper (which is the default, see ) + To ensure the construction of a valid JSON array the combination of + OMIT QUOTES and WITH WRAPPER + (which is the default, see ) is not permitted. @@ -18973,34 +18952,33 @@ DETAIL: Missing "]" after array dimensions. on_empty_set on_empty_value + + alternative ON { ERROR | EMPTY } + - - alternative - ON { ERROR | EMPTY } - - - - These clauses all provide for an alternative behavior when the result of path_expression - evaulation results in either an error or no results at all. The different clauses simply - specify a different subset of options that matches the expectations described in the - function definitions. Specify ERROR or EMPTY as - appropriate to the clause you are writing. + These clauses all provide for an alternative behavior when the evaluation + of path_expression either results in an error + or produces an empty set. The ON ERROR behavior also + applies to errors that occur when enforcing the + returning_clause. - For json_exists (on_error_boolean), + For JSON_EXISTS (... on_error_boolean), alternative can be: ERROR, UNKNOWN, TRUE, FALSE. - For json_query (on_error_set, and on_empty_set), - alternative can be: ERROR, NULL, - EMPTY ARRAY, EMPTY OBJECT, or DEFAULT - followed by an expression. + For JSON_QUERY (... on_error_set + on_empty_set), alternative can be: + ERROR, NULL, EMPTY ARRAY, + EMPTY OBJECT, or DEFAULT followed by an + expression. - For json_value (on_error_value, and on_empty_value), - alternative can be: ERROR, NULL, - or DEFAULT followed by an expression. + For JSON_VALUE (... on_error_set + on_empty_set), alternative can be: + ERROR, NULL, or DEFAULT + followed by an expression. -- 2.43.0