On Fri, Jul 5, 2024 at 8:35 PM Amit Langote <amitlangot...@gmail.com> wrote:
> Please check the attached. I've also added <itemizedlist> lists as I
> remember you had proposed before to make the functions' descriptions a
> bit more readable -- I'm persuaded. :-)
>
json_exists
"Returns true if the SQL/JSON path_expression applied to the
context_item using the PASSING values yields any items."
now you changed to
<<
Returns true if the SQL/JSON path_expression applied to the
context_item. path_expression can reference variables named in the
PASSING clause.
<<
Is it wrong?
For both <literal>ON EMPTY</literal>and <literal>ON ERROR</literal>,
specifying <literal>ERROR</literal> will cause an error to be
thrown with
the appropriate message. Other options include returning a SQL NULL, an
need one more whitespace. should be:
For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,
Note that an error will be thrown if multiple values are returned and
<literal>WITHOUT WRAPPER</literal> is specified.
since not specify error on error, then no error will be thrown. maybe
rephrase to
It will be evaulated as error if multiple values are returned and
<literal>WITHOUT WRAPPER</literal> is specified.
<para>
For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,
specifying <literal>ERROR</literal> will cause an error to be
thrown with
the appropriate message. Other options include returning a SQL NULL, an
empty array or object (array by default), or a user-specified expression
that can be coerced to jsonb or the type specified in
<literal>RETURNING</literal>.
The default when <literal>ON EMPTY</literal> or <literal>ON
ERROR</literal>
is not specified is to return a SQL NULL value when the respective
situation occurs.
</para>
in here, "empty array or object (array by default)",
I don't think people can understand the meaning of "(array by default)" .
"or a user-specified expression"
maybe we can change to
"or a user-specified
<literal>DEFAULT</literal> <replaceable>expression</replaceable>"
I think "user-specified expression" didn't have much link with
"<literal>DEFAULT</literal> <replaceable>expression</replaceable>"
<replaceable>path_expression</replaceable> can reference variables named
in the <literal>PASSING</literal> clause.
do we need "The <replaceable>path_expression</replaceable>"?
also maybe we can add
+ In <literal>PASSING</literal> clause, <replaceable>varname</replaceable> is
+ the variables name, <replaceable>value</replaceable> is the
+ variables' value.
we can add a PASSING clause example from sqljson_queryfuncs.sql ,
since all three functions can use it.
JSON_VALUE:
<<an error is thrown if that's not the case (though see the discussion
of ON ERROR below).
then
<< The ON ERROR and ON EMPTY clauses have similar semantics as
mentioned in the description of JSON_QUERY, except the set of values
returned in lieu of throwing an error is different.
you first refer "below", then director to JSON_QUERY on error, on
empty description.
is the correct usage of "below"?
"(though see the discussion of ON ERROR below)."
i am not sure the meaning of "though" even watched this
https://www.youtube.com/watch?v=r-LphuCKQ0Q
