On 2022-07-08 Fr 16:20, Andrew Dunstan wrote:
> On 2022-07-08 Fr 16:03, Erik Rijkers wrote:
>> Hi,
>>
>> Attached are a few small changes to the JSON_TABLE section in func.sgml.
>>
>> The first two changes are simple typos.
>>
>> Then there was this line:
>>
>> ----
>> context_item, path_expression [ AS json_path_name ] [ PASSING { value
>> AS varname } [, ...]]
>> ----
>>
>> those are the parameters to JSON_TABLE() so I changed that line to:
>>
>> ----
>> JSON_TABLE(context_item, path_expression [ AS json_path_name ] [
>> PASSING { value AS varname } [, ...]])
>> ----
>>
>> Some parts of the JSON_TABLE text strike me as opaque. For instance,
>> there are paragraphs that more than once use the term:
>> json_api_common_syntax
>>
>> 'json_api_common_syntax' is not explained. It turns out it's a relic
>> from Nikita's original docs. I dug up a 2018 patch where the term is
>> used as:
>>
>> ---- 2018:
>> JSON_TABLE (
>> json_api_common_syntax [ AS path_name ]
>> COLUMNS ( json_table_column [, ...] )
>> (etc...)
>> ----
>>
>> with explanation:
>>
>> ---- 2018:
>> json_api_common_syntax:
>> The input data to query, the JSON path expression defining the
>> query, and an optional PASSING clause.
>> ----
>>
>> So that made sense then (input+jsonpath+params=api), but it doesn't
>> now fit as such in the current docs.
>>
>> I think it would be best to remove all uses of that compound term, and
>> rewrite the explanations using only the current parameter names
>> (context_item, path_expression, etc).
>>
>> But I wasn't sure and I haven't done any such changes in the attached.
>>
>> Perhaps I'll give it a try during the weekend.
>>
>>
>>
>
> Thanks for this. If you want to follow up that last sentence I will try
> to commit a single fix early next week.
>
>
Here's a patch that deals with most of this. There's one change you
wanted that I don't think is correct, which I omitted.
cheers
andrew
--
Andrew Dunstan
EDB: https://www.enterprisedb.com
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index b6783b7ad0..478d6eccd8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -18030,9 +18030,9 @@ FROM
or array, but if it is <literal>CONDITIONAL</literal> it will not be
applied to a single array or object. <literal>UNCONDITIONAL</literal>
is the default.
- If the result is a a scalar string, by default the value returned will have
- surrounding quotes making it a valid JSON value. However, this behavior
- is reversed if <literal>OMIT QUOTES</literal> is specified.
+ If the result is a scalar string, by default the value returned will
+ have surrounding quotes making it a valid JSON value. However, this
+ behavior is reversed if <literal>OMIT QUOTES</literal> is specified.
The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
clauses have similar semantics to those clauses for
<function>json_value</function>.
@@ -18101,7 +18101,7 @@ FROM
columns. Columns produced by <literal>NESTED PATH</literal>s at the
same level are considered to be <firstterm>siblings</firstterm>,
while a column produced by a <literal>NESTED PATH</literal> is
- considered to be a child of the column produced by and
+ considered to be a child of the column produced by a
<literal>NESTED PATH</literal> or row expression at a higher level.
Sibling columns are always joined first. Once they are processed,
the resulting rows are joined to the parent row.
@@ -18151,9 +18151,9 @@ FROM
the specified column.
</para>
<para>
- The provided <literal>PATH</literal> expression parses the
- row pattern defined by <parameter>json_api_common_syntax</parameter>
- and fills the column with produced SQL/JSON items, one for each row.
+ The provided <literal>PATH</literal> expression is evaluated and
+ and the column is filled with the produced SQL/JSON items, one for each
+ row.
If the <literal>PATH</literal> expression is omitted,
<function>JSON_TABLE</function> uses the
<literal>$.<replaceable>name</replaceable></literal> path expression,
@@ -18185,9 +18185,8 @@ FROM
item into each row of this column.
</para>
<para>
- The provided <literal>PATH</literal> expression parses the
- row pattern defined by <parameter>json_api_common_syntax</parameter>
- and fills the column with produced SQL/JSON items, one for each row.
+ The provided <literal>PATH</literal> expression is evaluated and
+ the column is filled with the produced SQL/JSON items, one for each row.
If the <literal>PATH</literal> expression is omitted,
<function>JSON_TABLE</function> uses the
<literal>$.<parameter>name</parameter></literal> path expression,
@@ -18216,11 +18215,10 @@ FROM
Generates a column and inserts a boolean item into each row of this column.
</para>
<para>
- The provided <literal>PATH</literal> expression parses the
- row pattern defined by <parameter>json_api_common_syntax</parameter>,
- checks whether any SQL/JSON items were returned, and fills the column with
- resulting boolean value, one for each row.
- The specified <parameter>type</parameter> should have cast from
+ The provided <literal>PATH</literal> expression is evaluated,
+ a check whether any SQL/JSON items were returned is done, and
+ the column is filled with the resulting boolean value, one for each row.
+ The specified <parameter>type</parameter> should have a cast from the
<type>boolean</type>.
If the <literal>PATH</literal> expression is omitted,
<function>JSON_TABLE</function> uses the
