rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Improve readability of SQL/JSON documentation. 

Per review from Justin Pryzby.

Discussion: https://postgr.es/m/f50aca87-6b35-a1b0-2286-f815a589dd83@dunslane.net
This commit is contained in:
Andrew Dunstan 2022-04-11 11:48:40 -04:00
parent c215cc7b61
commit b46bcf7a4b
1 changed files with 14 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/src/sgml/func.sgml
View File

@ -17764,7 +17764,7 @@ $.* ? (@ like_regex "^\\d+$")
<sect5> <sect5>
<title>Examples</title> <title>Examples</title>
<para> <para>
Construct a JSON the provided strings: Construct JSON using the provided strings:
</para> </para>
<screen> <screen>
SELECT JSON('{ "a" : 123, "b": [ true, "foo" ], "a" : "bar" }'); SELECT JSON('{ "a" : 123, "b": [ true, "foo" ], "a" : "bar" }');
@ -17819,7 +17819,7 @@ ERROR: duplicate JSON object key value
<acronym>JSON</acronym> value. <acronym>JSON</acronym> value.
For null input, <acronym>SQL</acronym> null For null input, <acronym>SQL</acronym> null
(not a <acronym>JSON</acronym> null) value is returned. (not a <acronym>JSON</acronym> null) value is returned.
For any scalar other than a number or a Boolean the text For any scalar other than a number or a Boolean, the text
representation will be used, with escaping as necessary to make representation will be used, with escaping as necessary to make
it a valid <acronym>JSON</acronym> string value. it a valid <acronym>JSON</acronym> string value.
For details, see For details, see
@ -17855,7 +17855,7 @@ ERROR: duplicate JSON object key value
<sect5> <sect5>
<title>Examples</title> <title>Examples</title>
<para> <para>
Construct a JSON from the provided values various types: Construct JSON scalars from the provided values of various types:
</para> </para>
<screen> <screen>
SELECT JSON_SCALAR(123.45); SELECT JSON_SCALAR(123.45);
@ -18113,9 +18113,7 @@ WHERE f.did = 103;
<para> <para>
The <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 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> stored in different table columns into pairs.
or an <command>ORDER BY</command> clause, this function returns a separate JSON object
for each table row.
</para> </para>
</sect5> </sect5>
@ -18691,7 +18689,7 @@ INSERT INTO my_films VALUES (
<title>Description</title> <title>Description</title>
<para> <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. <acronym>JSON</acronym> path expression can return any <acronym>SQL/JSON</acronym> items.
</para> </para>
</sect5> </sect5>
@ -18804,7 +18802,7 @@ SELECT JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]');
<title>Description</title> <title>Description</title>
<para> <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. <acronym>JSON</acronym> data and converts it to an <acronym>SQL</acronym> scalar.
If the specified JSON path expression returns more than one If the specified JSON path expression returns more than one
<acronym>SQL/JSON</acronym> item, an error occurs. To extract <acronym>SQL/JSON</acronym> item, an error occurs. To extract
@ -18963,7 +18961,7 @@ SELECT JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 1 ON ERROR);
<title>Description</title> <title>Description</title>
<para> <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 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 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. items, you must wrap the result using the <literal>WITH WRAPPER</literal> clause.
@ -19366,7 +19364,7 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
<title>Description</title> <title>Description</title>
<para> <para>
<function>JSON_TABLE</function> function queries <acronym>JSON</acronym> data The <function>JSON_TABLE</function> function queries <acronym>JSON</acronym> data
and presents the results as a relational view, which can be accessed as a and presents the results as a relational view, which can be accessed as a
regular SQL table. You can only use <function>JSON_TABLE</function> inside the regular SQL table. You can only use <function>JSON_TABLE</function> inside the
<literal>FROM</literal> clause of the <literal>SELECT</literal> statement <literal>FROM</literal> clause of the <literal>SELECT</literal> statement
@ -19620,7 +19618,7 @@ where <replaceable class="parameter">json_table_column</replaceable> is:
<para> <para>
The optional <replaceable>json_path_name</replaceable> serves as an The optional <replaceable>json_path_name</replaceable> serves as an
identifier of the provided <replaceable>json_path_specification</replaceable>. identifier of the provided <replaceable>json_path_specification</replaceable>.
The path name must be unique and cannot coincide with column names. The path name must be unique and distinct from the column names.
When using the <literal>PLAN</literal> clause, you must specify the names When using the <literal>PLAN</literal> clause, you must specify the names
for all the paths, including the row pattern. Each path name can appear in for all the paths, including the row pattern. Each path name can appear in
the <literal>PLAN</literal> clause only once. the <literal>PLAN</literal> clause only once.
@ -19820,7 +19818,7 @@ JSON_SERIALIZE (
<title>Description</title> <title>Description</title>
<para> <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. into a character or binary string.
</para> </para>
</sect5> </sect5>
@ -19872,7 +19870,7 @@ JSON_SERIALIZE (
<sect5> <sect5>
<title>Examples</title> <title>Examples</title>
<para> <para>
Construct a JSON the provided strings: Construct serialized JSON using the provided strings:
</para> </para>
<screen> <screen>
SELECT JSON_SERIALIZE(JSON_SCALAR('foo')); SELECT JSON_SERIALIZE(JSON_SCALAR('foo'));
@ -19961,7 +19959,7 @@ SELECT JSON_SERIALIZE('{"foo": "bar", "baz": [1, 2]}' RETURNING bytea);
supports the following types: <type>json</type>, <type>jsonb</type>, supports the following types: <type>json</type>, <type>jsonb</type>,
<type>bytea</type>, and character string types (<type>text</type>, <type>char</type>, <type>bytea</type>, and character string types (<type>text</type>, <type>char</type>,
<type>varchar</type>, and <type>nchar</type>). <type>varchar</type>, and <type>nchar</type>).
To use other types, you must create the <literal>CAST</literal> from <type>json</type> for this type. To use another type, you must create a cast from <type>json</type> to that type.
By default, the <type>json</type> type is returned. By default, the <type>json</type> type is returned.
</para> </para>
<para> <para>
@ -22392,7 +22390,7 @@ SELECT NULLIF(value, '(none)') ...
Collects all the key/value pairs into a JSON object. Key arguments Collects all the key/value pairs into a JSON object. Key arguments
are coerced to text; value arguments are converted as per are coerced to text; value arguments are converted as per
<function>to_json</function> or <function>to_jsonb</function> <function>to_json</function> or <function>to_jsonb</function>
Values can be null, but not keys. Values can be null, but keys cannot.
</para></entry> </para></entry>
<entry>No</entry> <entry>No</entry>
</row> </row>
@ -22449,7 +22447,7 @@ SELECT NULLIF(value, '(none)') ...
Collects all the key/value pairs into a JSON object. Key arguments Collects all the key/value pairs into a JSON object. Key arguments
are coerced to text; value arguments are converted as per are coerced to text; value arguments are converted as per
<function>to_json</function> or <function>to_jsonb</function>. <function>to_json</function> or <function>to_jsonb</function>.
Values can be null, but not keys. Values can be null, but keys cannot.
If there is a duplicate key an error is thrown. If there is a duplicate key an error is thrown.
</para></entry> </para></entry>
<entry>No</entry> <entry>No</entry>