v2-0001-doc-json-query_9-16-3.patch

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+$")
    <replaceable>path_expression</replaceable> (the query) to a
    <replaceable>context_item</replaceable> (the document); see
    <xref linkend="functions-sqljson-path"/> for more details on what
-   <replaceable>path_expression</replaceable> can contain.
+   <replaceable>path_expression</replaceable> can contain.  Spoiler,
+   it can contain variable names, and so there is a standard, optional,
+   <literal>variable_definitions</literal> clause that can be used to
+   passing in values for those variables.
+  </para>
+
+  <para>
+   The different components of the SQL/JSON query function signatures are
+   described following the table. Both the <function>json_query</function>
+   and <function>json_value</function> functions are polymorphic in their
+   return type, yielding the value indicated by default by able to
+   be overridden by adding a <literal>return_clause</literal> or
+   <literal>return_data_type</literal> clause respectively.
+  </para>
+
+  <para>
+   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 <literal>on_error_*</literal> and <literal>on_error_*</literal>
+   clauses.
   </para>
 
   <table id="functions-sqljson-querying">
@@ -18692,14 +18712,15 @@ $.* ? (@ like_regex "^\\d+$")
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_exists</primary></indexterm>
         <function>json_exists</function> (
-        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
-        <optional> { <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>)
+        <replaceable>context_item</replaceable>,
+        <replaceable>path_expression</replaceable>
+        <optional>variable_definitions</optional>
+        <optional>on_error_boolean</optional>)
+        <returnvalue></returnvalue> <type>boolean</type>
        </para>
        <para>
         Returns true if the SQL/JSON <replaceable>path_expression</replaceable>
-        applied to the <replaceable>context_item</replaceable> using the
-        <literal>PASSING</literal> <replaceable>value</replaceable>s yields any
-        items.
+        applied to the <replaceable>context_item</replaceable> yields any items.
        </para>
        <para>
         The <literal>ON ERROR</literal> clause specifies the behavior if
@@ -18732,57 +18753,27 @@ ERROR:  jsonpath array subscript is out of bounds
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_query</primary></indexterm>
         <function>json_query</function> (
-        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
-        <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
-        <optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
-        <optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>EMPTY</literal> { <optional> <literal>ARRAY</literal> </optional> | <literal>OBJECT</literal> } | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
+        <replaceable>context_item</replaceable>,
+        <replaceable>path_expression</replaceable>
+        <optional>variable_definitions</optional>
+        <optional>return_clause</optional>
+        <optional>wrapping_clause</optional>
+        <optional>quoting_clause</optional>
+        <optional>on_empty_set</optional>
+        <optional>on_error_set</optional>)
+        <returnvalue></returnvalue> { <type>jsonb</type> | <varname>return_data_type</varname> }
       </para>
        <para>
         Returns the result of applying the SQL/JSON
         <replaceable>path_expression</replaceable> to the
-        <replaceable>context_item</replaceable> using the
-        <literal>PASSING</literal> <replaceable>value</replaceable>s.
-       </para>
-       <para>
-        If the path expression returns multiple SQL/JSON items, it might be
-        necessary to wrap the result using the <literal>WITH WRAPPER</literal>
-        clause to make it a valid JSON string.  If the wrapper is
-        <literal>UNCONDITIONAL</literal>, an array wrapper will always be
-        applied, even if the returned value is already a single JSON object
-        or an array.  If it is <literal>CONDITIONAL</literal>, it will not be
-        applied to a single JSON object or an array.
-        <literal>UNCONDITIONAL</literal> is the default.
-       </para>
-       <para>
-        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 <literal>KEEP QUOTES</literal>.  Conversely,
-        quotes can be omitted by specifying <literal>OMIT QUOTES</literal>.
-        Note that <literal>OMIT QUOTES</literal> cannot be specified when
-        <literal>WITH WRAPPER</literal> is also specified.
-       </para>
-       <para>
-        The <literal>RETURNING</literal> clause can be used to specify the
-        <replaceable>data_type</replaceable> of the result value.  By default,
-        the returned value will be of type <type>jsonb</type>.
+        <replaceable>context_item</replaceable>.
        </para>
        <para>
-        The <literal>ON EMPTY</literal> clause specifies the behavior if
-        evaluating <replaceable>path_expression</replaceable> yields no value
-        at all. The default when <literal>ON EMPTY</literal> is not specified
-        is to return a null value.
-       </para>
-       <para>
-        The <literal>ON ERROR</literal> clause specifies the
-        behavior if an error occurs when evaluating
-        <replaceable>path_expression</replaceable>, including the operation to
-        coerce the result value to the output type, or during the execution of
-        <literal>ON EMPTY</literal> behavior (that is caused by empty result
-        of <replaceable>path_expression</replaceable> evaluation).  The default
-        when <literal>ON ERROR</literal> 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.
        </para>
        <para>
         Examples:
@@ -18809,17 +18800,19 @@ DETAIL:  Missing "]" after array dimensions.
       <entry role="func_table_entry"><para role="func_signature">
         <indexterm><primary>json_value</primary></indexterm>
         <function>json_value</function> (
-        <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
-        <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
-        <optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
-        <optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
+        <replaceable>context_item</replaceable>,
+        <replaceable>path_expression</replaceable>
+        <optional>variable_definitions</optional>
+        <optional>return_type</optional>
+        <optional>on_empty_value</optional>
+        <optional>on_error_value</optional>)
+        <returnvalue></returnvalue> { <type>text</type> | <varname>return_data_type</varname> }
        </para>
        <para>
-        Returns the result of applying the SQL/JSON
+        Returns the result of applying the SQL/JSON scalar-producing
         <replaceable>path_expression</replaceable> to the
-        <replaceable>context_item</replaceable> using the
-        <literal>PASSING</literal> <replaceable>value</replaceable>s.
+        <replaceable>context_item</replaceable> and, by default,
+        converting it to SQL <type>text</type>.
        </para>
        <para>
         The extracted value must be a single <acronym>SQL/JSON</acronym>
@@ -18827,21 +18820,6 @@ DETAIL:  Missing "]" after array dimensions.
         that extracted value might be an object or an array, use the
         <function>json_query</function> function instead.
        </para>
-       <para>
-        The <literal>RETURNING</literal> clause can be used to specify the
-        <replaceable>data_type</replaceable> of the result value. By default,
-        the returned value will be of type <type>text</type>.
-       </para>
-       <para>
-        The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
-        clauses have similar semantics as mentioned in the description of
-        <function>json_query</function>.
-       </para>
-       <para>
-        Note that scalar strings returned by <function>json_value</function>
-        always have their quotes removed, equivalent to specifying
-        <literal>OMIT QUOTES</literal> in <function>json_query</function>.
-       </para>
        <para>
         Examples:
        </para>
@@ -18861,6 +18839,173 @@ DETAIL:  Missing "]" after array dimensions.
     </tbody>
    </tgroup>
   </table>
+
+  <variablelist>
+   <varlistentry id="json-query-context-item">
+    <term><varname>context_item</varname></term>
+    <listitem>
+     <para>
+      <literal>castable_expression</literal>
+     </para>
+     <para>
+      A value expression capable of being cast to the <type>jsonb</type> type.
+      Failure during casting will result in function execution failure, regardless
+      of the setting for the <literal>ON ERROR</literal> clause.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-path-expression">
+    <term><varname>path_expression</varname></term>
+    <listitem>
+     <para>
+      <literal>jsonpath_expression</literal>
+     </para>
+     <para>
+      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.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-variable-definitons">
+    <term><varname>variable_definitions</varname></term>
+    <listitem>
+     <para>
+      <optional>
+       <literal>PASSING</literal> {
+        <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable>
+       }
+       <optional>, ...</optional>
+      </optional>
+     </para>
+     <para>
+      If the <literal>path_expression</literal> contains JSONPath variable expression write
+      <literal>PASSING</literal> after the expression and then provide a comma-separated
+      list of values, mapped to names using the <literal>AS</literal> keyword.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-return-type">
+    <term><varname>return_data_type</varname></term>
+    <listitem>
+     <para>
+      <optional> data_type_identifier </optional>
+     </para>
+     <para>
+      The <function>json_value</function> 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 <type>text</type>, with the JSON null value being converted to an SQL null value.
+      You may specify <type>jsonb</type> or <type>json</type>, in which case the computed scalar result
+      will be returned as-is, including the JSON null value.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-return-clause">
+    <term><varname>return_clause</varname></term>
+    <listitem>
+     <para>
+      <optional>
+       RETURNING <replaceable>return_data_type</replaceable>
+       <optional>
+        <literal>FORMAT JSON</literal>
+        <optional>
+         <literal>ENCODING UTF8</literal>
+        </optional>
+       </optional>
+      </optional>
+     </para>
+     <para>
+      The <function>json_query</function> function is polymorphic in its output type with this return_clause
+      clause dictating what that type is.  The default is <type>jsonb</type> in <literal>UTF8</literal> encoding.
+      This is what you receive if you omit the entire clause.
+     </para>
+     <para>
+      The optional format and encoding clauses may only be used if the <literal>data_type</literal> is an SQL character type.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-result-wrapping">
+    <term><varname>wrapping_clause</varname></term>
+    <listitem>
+     <para>
+      <optional> <literal>WITHOUT</literal> <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
+      <optional> <literal>WITH</literal><optional> <literal>UNCONDITIONAL</literal> </optional><optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
+      <optional> <literal>WITH</literal><literal>CONDITIONAL</literal><optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
+     </para>
+     <para>
+      The <function>json_query</function> function can produce multiple JSON values, either as an object or a set,
+      as a result of evaluating the <literal>path_expression</literal>.  The <literal>WITHOUT</literal>
+      variant will simply return the result as-is, possibly resulting in a error in the set case.  The default
+      <literal>WITH</literal> 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 <literal>CONDITIONAL</literal>
+      keyword after <literal>WITH</literal>.
+     </para>
+     <para>
+      The default behavior is to unconditionally wrap the result in an array.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-result-quoting">
+    <term><varname>quoting_clause</varname></term>
+    <listitem>
+     <para>
+      <optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> ON SCALAR STRING </optional> </optional>
+     </para>
+     <para>
+      The <function>json_query</function> function outputs <type>jsonb</type> values; therefore a single scalar text result
+      will be quoted.  Specify <literal>OMIT QUOTES</literal> to remove the quotes and thus producing a result that can
+      be cast to <type>text</type>.
+     </para>
+     <para>
+      The optional <literal>ON SCALAR STRING</literal> modifier represents the default behavior.
+     </para>
+     <para>
+      To ensure the construction of a valid JSON array the combination of omit quotes and producing an
+      unconditional wrapper (which is the default, see <xref linkend="json-query-result-wrapping"/>)
+      is not permitted.
+     </para>
+    </listitem>
+   </varlistentry>
+   <varlistentry id="json-query-on-error-empty">
+    <term><varname>on_error_boolean</varname></term>
+    <term><varname>on_error_set</varname></term>
+    <term><varname>on_error_value</varname></term>
+    <term><varname>on_empty_set</varname></term>
+    <term><varname>on_empty_value</varname></term>
+    <listitem>
+     <para>
+      <optional>
+        <replaceable>alternative</replaceable>
+        <literal>ON</literal> { <literal>ERROR</literal> | <literal>EMPTY</literal> }
+      </optional>
+     </para>
+     <para>
+      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 <literal>ERROR</literal> or <literal>EMPTY</literal> as
+      appropriate to the clause you are writing.
+     </para>
+     <para>
+      For <function>json_exists</function> (<literal>on_error_boolean</literal>),
+      <literal>alternative</literal> can be: <literal>ERROR</literal>, <literal>UNKNOWN</literal>,
+      <literal>TRUE</literal>, <literal>FALSE</literal>.
+     </para>
+     <para>
+      For <function>json_query</function> (<literal>on_error_set, and on_empty_set</literal>),
+      <literal>alternative</literal> can be: <literal>ERROR</literal>, <literal>NULL</literal>,
+      <literal>EMPTY ARRAY</literal>, <literal>EMPTY OBJECT</literal>, or <literal>DEFAULT</literal>
+      followed by an expression.
+     </para>
+     <para>
+      For <function>json_value</function> (<literal>on_error_value, and on_empty_value</literal>),
+      <literal>alternative</literal> can be: <literal>ERROR</literal>, <literal>NULL</literal>,
+      or <literal>DEFAULT</literal> followed by an expression.
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+
   </sect2>
 
  <sect2 id="functions-sqljson-table">