diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index c324906b22..796f61138a 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18668,7 +18668,27 @@ $.* ? (@ like_regex "^\\d+$")
path_expression (the query) to a
context_item (the document); see
for more details on what
- path_expression can contain.
+ 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.
@@ -18692,14 +18712,15 @@ $.* ? (@ like_regex "^\\d+$")
json_exists
json_exists (
- context_item, path_expression PASSING { value AS varname } , ...
- { TRUE | FALSE | UNKNOWN | ERROR } ON ERROR )
+ context_item,
+ path_expression
+ variable_definitions
+ on_error_boolean)
+ boolean
Returns true if the SQL/JSON path_expression
- applied to the context_item using the
- PASSING values yields any
- items.
+ applied to the context_item yields any items.
The ON ERROR clause specifies the behavior if
@@ -18732,57 +18753,27 @@ 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 )
+ context_item,
+ path_expression
+ variable_definitions
+ return_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 using the
- PASSING values.
-
-
- 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
- UNCONDITIONAL, an array wrapper will always be
- applied, even if the returned value is already a single JSON object
- or an array. If it is CONDITIONAL, it will not be
- applied to a single JSON object or an array.
- UNCONDITIONAL is the default.
-
-
- If the result is a scalar string, by default, the returned value will
- be surrounded by quotes, making it a valid JSON value. It can be made
- explicit by specifying KEEP QUOTES. Conversely,
- quotes can be omitted by specifying OMIT QUOTES.
- Note that OMIT QUOTES cannot be specified when
- WITH WRAPPER is also specified.
-
-
- 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.
+ context_item.
- The ON EMPTY clause specifies the behavior if
- evaluating path_expression yields no value
- at all. The default when ON EMPTY is not specified
- is to return a null value.
-
-
- 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
- of path_expression evaluation). The default
- when ON ERROR is not specified is to return a null
- value.
+ 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
+ the desired value as an SQL type.
Examples:
@@ -18809,17 +18800,19 @@ 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 )
+ context_item,
+ path_expression
+ variable_definitions
+ return_type
+ on_empty_value
+ on_error_value)
+ { text | return_data_type }
- Returns the result of applying the SQL/JSON
+ Returns the result of applying the SQL/JSON scalar-producing
path_expression to the
- context_item using the
- PASSING values.
+ context_item and, by default,
+ converting it to SQL text.
The extracted value must be a single SQL/JSON
@@ -18827,21 +18820,6 @@ DETAIL: Missing "]" after array dimensions.
that extracted value might be an object or an array, use the
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.
-
-
- The ON ERROR and ON EMPTY
- clauses have similar semantics as mentioned in the description of
- json_query.
-
-
- Note that scalar strings returned by json_value
- always have their quotes removed, equivalent to specifying
- OMIT QUOTES in json_query.
-
Examples:
@@ -18861,6 +18839,173 @@ DETAIL: Missing "]" after array dimensions.
+
+
+
+ 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
+ }
+ , ...
+
+
+
+ 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.
+
+
+
+
+ return_clause
+
+
+
+ RETURNING return_data_type
+
+ FORMAT JSON
+
+ ENCODING UTF8
+
+
+
+
+
+ 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.
+
+
+ The optional format and encoding clauses may only be used if the data_type is an SQL character type.
+
+
+
+
+ wrapping_clause
+
+
+ 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.
+
+
+
+
+ quoting_clause
+
+
+ { 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.
+
+
+ To ensure the construction of a valid JSON array the combination of omit quotes and producing an
+ unconditional wrapper (which is the default, see )
+ is not permitted.
+
+
+
+
+ on_error_boolean
+ on_error_set
+ on_error_value
+ on_empty_set
+ on_empty_value
+
+
+
+ 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.
+
+
+ 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_value (on_error_value, and on_empty_value),
+ alternative can be: ERROR, NULL,
+ or DEFAULT followed by an expression.
+
+
+
+
+