On 2021-01-20 03:49, Nikita Glukhov wrote:
[0001-Add-common-SQL-JSON-clauses-v52.patch.gz]
[0002-SQL-JSON-constructors-v52.patch.gz]
[0003-IS-JSON-predicate-v52.patch.gz]
[0004-SQL-JSON-query-functions-v52.patch.gz]
[0005-SQL-JSON-functions-for-json-type-v52.patch.gz]
[0006-GUC-sql_json-v52.patch.gz]
Hi,
I read through the file func.sgml (only that file) and put the
errors/peculiarities in the attached diff. (Small stuff; typos really)
Your patch includes a CREATE TABLE my_films + INSERT, to run the
examples against. I think this is a great idea and we should do it more
often.
But, the table has a text-column to contain the subsequently inserted
json values. The insert runs fine but it turns out that some later
examples queries only run against a jsonb column. So I propose to
change:
CREATE TABLE my_films (js text);
to:
CREATE TABLE my_films (js jsonb);
This change is not yet included in the attached file. An alternative
would be to cast the text-column in the example queries as js::jsonb
I also noticed that some errors were different in the sgml file than 'in
the event':
SELECT JSON_QUERY(js, '$.favorites[*].kind' ERROR ON ERROR) FROM
my_films_jsonb;
(table 'my_films_jsonb' is the same as your 'my_films', but with js
as a jsonb column)
manual says: "ERROR: more than one SQL/JSON item"
in reality: "ERROR: JSON path expression in JSON_QUERY should return
singleton item without wrapper"
and: "HINT: use WITH WRAPPER clause to wrap SQL/JSON item
sequence into array"
Thanks,
Erik Rijkers
--
Nikita Glukhov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
--- ./doc/src/sgml/func.sgml.orig 2021-01-20 14:52:35.564407275 +0100
+++ ./doc/src/sgml/func.sgml 2021-01-23 11:09:11.582465755 +0100
@@ -16968,7 +16968,7 @@
</itemizedlist>
<para>
- All SQL/JSON functions fall into one of the two groups.
+ All SQL/JSON functions fall into one of two groups.
<link linkend="functions-sqljson-producing">Constructor functions</link>
generate JSON data from values of SQL types.
<link linkend="functions-sqljson-querying">Query functions</link>
@@ -17034,7 +17034,7 @@
<title>Description</title>
<para>
- <function>JSON</function> function generates a <acronym>JSON</acronym>
+ The <function>JSON</function> function generates a <acronym>JSON</acronym>
from a text data.
</para>
</sect5>
@@ -17049,7 +17049,7 @@
<listitem>
<para>
String expression that provides the <acronym>JSON</acronym> text data.
- Accepted any character strings (<type>text</type>, <type>char</type>, etc.)
+ Accepts any character strings (<type>text</type>, <type>char</type>, etc.)
or binary strings (<type>bytea</type>) in UTF8 encoding.
For null input, <acronym>SQL</acronym> null value is returned.
</para>
@@ -17110,7 +17110,7 @@
<sect5>
<title>Notes</title>
<para>
- Alternatively, you can construct <acronym>JSON</acronym> values simply
+ Alternatively, you can construct <acronym>JSON</acronym> values by simply
using <productname>PostgreSQL</productname>-specific casts to
<type>json</type> and <type>jsonb</type> types.
</para>
@@ -17118,7 +17118,7 @@
<sect5>
<title>Examples</title>
<para>
- Construct a JSON the provided strings:
+ Construct a JSON using the provided strings:
</para>
<screen>
SELECT JSON('{ "a" : 123, "b": [ true, "foo" ], "a" : "bar" }');
@@ -17173,7 +17173,7 @@
<acronym>JSON</acronym>.
For null input, <acronym>SQL</acronym> null
(not a <acronym>JSON</acronym> null) value is returned.
- For any scalar other than a number, a Boolean, the text representation
+ For any scalar other than a number or a Boolean, the text representation
will be used, with escaping as necessary to make it a valid
<acronym>JSON</acronym> string value.
For details, see
@@ -17208,7 +17208,7 @@
<sect5>
<title>Examples</title>
<para>
- Construct a JSON from the provided values various types:
+ Construct a JSON from the provided value of various type:
</para>
<screen>
SELECT JSON_SCALAR(123.45);
@@ -17250,7 +17250,7 @@
<title>Description</title>
<para>
- <function>JSON_OBJECT</function> function generates a <acronym>JSON</acronym>
+ The <function>JSON_OBJECT</function> function generates a <acronym>JSON</acronym>
object from <acronym>SQL</acronym> or <acronym>JSON</acronym> data.
</para>
</sect5>
@@ -17463,7 +17463,7 @@
<title>Description</title>
<para>
- <function>JSON_OBJECTAGG</function> function aggregates the provided data
+ The <function>JSON_OBJECTAGG</function> function aggregates the provided data
into a <acronym>JSON</acronym> object. You can use this function to combine values
stored in different table columns into pairs. If you specify a <command>GROUP BY</command>
or an <command>ORDER BY</command> clause, this function returns a separate JSON object
@@ -17689,7 +17689,7 @@
<title>Description</title>
<para>
- <function>JSON_ARRAY</function> function constructs a <acronym>JSON</acronym> array from
+ The <function>JSON_ARRAY</function> function constructs a <acronym>JSON</acronym> array from
the provided <acronym>SQL</acronym> or <acronym>JSON</acronym> data.
</para>
</sect5>
@@ -17855,7 +17855,7 @@
<title>Description</title>
<para>
- <function>JSON_ARRAYAGG</function> function aggregates the provided <acronym>SQL</acronym>
+ The <function>JSON_ARRAYAGG</function> function aggregates the provided <acronym>SQL</acronym>
or <acronym>JSON</acronym> data into a <acronym>JSON</acronym> array.
</para>
</sect5>
@@ -18038,7 +18038,7 @@
<title>Description</title>
<para>
- <function>JSON_EXISTS</function> function checks whether the provided
+ The <function>JSON_EXISTS</function> function checks whether the provided
<acronym>JSON</acronym> path expression can return any <acronym>SQL/JSON</acronym> items.
</para>
</sect5>
@@ -18151,7 +18151,7 @@
<title>Description</title>
<para>
- <function>JSON_VALUE</function> function extracts a value from the provided
+ The <function>JSON_VALUE</function> function extracts a value from the provided
<acronym>JSON</acronym> data and converts it to an <acronym>SQL</acronym> scalar.
If the specified JSON path expression returns more than one
<acronym>SQL/JSON</acronym> item, an error occurs. To extract
@@ -18310,7 +18310,7 @@
<title>Description</title>
<para>
- <function>JSON_QUERY</function> function extracts an <acronym>SQL/JSON</acronym>
+ The <function>JSON_QUERY</function> function extracts an <acronym>SQL/JSON</acronym>
array or object from <acronym>JSON</acronym> data. This function must return
a JSON string, so if the path expression returns a scalar or multiple SQL/JSON
items, you must wrap the result using the <literal>WITH WRAPPER</literal> clause.
@@ -18532,7 +18532,7 @@
<title>Description</title>
<para>
- <command>IS JSON</command> predicate tests whether the provided value is valid
+ The <command>IS JSON</command> predicate tests whether the provided value is valid
<acronym>JSON</acronym> data. If you provide a specific JSON data type as a parameter,
you can check whether the value belongs to this type.
You can also use this predicate in the <command>IS NOT JSON</command> form.
@@ -18677,7 +18677,7 @@
</itemizedlist>
<sect4 id="functions-jsonserialize">
- <title><literal>JSON_SERIALAIZE</literal></title>
+ <title><literal>JSON_SERIALIZE</literal></title>
<indexterm><primary>json_serialize</primary></indexterm>
<synopsis>
@@ -18691,7 +18691,7 @@
<title>Description</title>
<para>
- <function>JSON_SERIALIZE</function> function transforms a SQL/JSON value
+ The <function>JSON_SERIALIZE</function> function transforms a SQL/JSON value
into a character or binary string.
</para>
</sect5>
@@ -18705,12 +18705,12 @@
</term>
<listitem>
<para>
- <acronym>JSON</acronym> typed expression that provides a data for
- serialization. Accepted JSON types (<type>json</type> and
+ <acronym>JSON</acronym> typed expression that provides data for
+ serialization. Accepted are JSON types (<type>json</type> and
<type>jsonb</type>), any character string types (<type>text</type>,
<type>char</type>, etc.), binary strings (<type>bytea</type>) in
UTF8 encoding.
- For null input, null value is returned.
+ For null input, a null value is returned.
</para>
<para>
The optional <literal>FORMAT</literal> clause is provided to conform
@@ -18743,7 +18743,7 @@
<sect5>
<title>Examples</title>
<para>
- Construct a JSON the provided strings:
+ Construct a JSON using a provided string:
</para>
<screen>
SELECT JSON_SERIALIZE(JSON_SCALAR('foo'));
