open-dsi
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

SQL/JSON: Various improvements to SQL/JSON query function docs

Browse Source 
1. Remove the keyword SELECT from the examples to be consistent
with the examples of other JSON-related functions listed on the
same page.

2. Add <synopsis> tags around the functions' syntax definition

3. Capitalize function names in the syntax synopsis and the examples

4. Use <itemizedlist> lists for dividing the descriptions of
   individual functions into bullet points

5. Significantly rewrite the description of wrapper clauses of
   JSON_QUERY

6. Significantly rewrite the descriptions of ON ERROR / EMPTY
   clauses of JSON_QUERY() and JSON_VALUE() functions

7. Add a note about how JSON_VALUE() and JSON_QUERY() differ when
   returning a JSON null result

8. Move the description of the PASSING clause from the descriptions
   of individual functions into the top paragraph

And other miscellaneous text improvements, typo fixes.

Suggested-by: Thom Brown <thom@linux.com>
Suggested-by: David G. Johnston <david.g.johnston@gmail.com>
Reviewed-by: Jian He <jian.universality@gmail.com>
Reviewed-by: Erik Rijkers <er@xs4all.nl>
Discussion: https://postgr.es/m/CAA-aLv7Dfy9BMrhUZ1skcg=OdqysWKzObS7XiDXdotJNF0E44Q@mail.gmail.com
Discussion: https://postgr.es/m/CAKFQuwZNxNHuPk44zDF7z8qZec1Aof10aA9tWvBU5CMhEKEd8A@mail.gmail.com
pull/166/head
Amit Langote 1 year ago
parent 571f7f7086
commit 42de72fa7b
1 changed files with 147 additions and 78 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 225
      doc/src/sgml/func.sgml

225
doc/src/sgml/func.sgml
Unescape View File

@ -18665,10 +18665,15 @@ $.* ? (@ like_regex "^\\d+$")
<literal>JSON_QUERY()</literal>, and <literal>JSON_VALUE()</literal> <literal>JSON_QUERY()</literal>, and <literal>JSON_VALUE()</literal>
described in <xref linkend="functions-sqljson-querying"/> can be used described in <xref linkend="functions-sqljson-querying"/> can be used
to query JSON documents. Each of these functions apply a to query JSON documents. Each of these functions apply a
<replaceable>path_expression</replaceable> (the query) to a <replaceable>path_expression</replaceable> (an SQL/JSON path query) to a
<replaceable>context_item</replaceable> (the document); see <replaceable>context_item</replaceable> (the document). See
<xref linkend="functions-sqljson-path"/> for more details on what <xref linkend="functions-sqljson-path"/> for more details on what
<replaceable>path_expression</replaceable> can contain. the <replaceable>path_expression</replaceable> can contain. The
<replaceable>path_expression</replaceable> can also reference variables,
whose values are specified with their respective names in the
<literal>PASSING</literal> clause that is supported by each function.
<replaceable>context_item</replaceable> can be a <type>jsonb</type> value
or a character string that can be successfully cast to <type>jsonb</type>.
</para> </para>
<table id="functions-sqljson-querying"> <table id="functions-sqljson-querying">
@ -18691,37 +18696,48 @@ $.* ? (@ like_regex "^\\d+$")
<row> <row>
<entry role="func_table_entry"><para role="func_signature"> <entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_exists</primary></indexterm> <indexterm><primary>json_exists</primary></indexterm>
<function>json_exists</function> ( <synopsis>
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional> <function>JSON_EXISTS</function> (
<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> <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>) <returnvalue>boolean</returnvalue>
</synopsis>
</para> </para>
<itemizedlist>
<listitem>
<para> <para>
Returns true if the SQL/JSON <replaceable>path_expression</replaceable> Returns true if the SQL/JSON <replaceable>path_expression</replaceable>
applied to the <replaceable>context_item</replaceable> using the applied to the <replaceable>context_item</replaceable> yields any
<literal>PASSING</literal> <replaceable>value</replaceable>s yields any items, false otherwise.
items.
</para> </para>
</listitem>
<listitem>
<para> <para>
The <literal>ON ERROR</literal> clause specifies the behavior if The <literal>ON ERROR</literal> clause specifies the behavior if
an error occurs; the default is to return the <type>boolean</type> an error occurs during <replaceable>path_expression</replaceable>
<literal>FALSE</literal> value. Note that if the evaluation. Specifying <literal>ERROR</literal> will cause an error to
<replaceable>path_expression</replaceable> is <literal>strict</literal> be thrown with the appropriate message. Other options include
and <literal>ON ERROR</literal> behavior is <literal>ERROR</literal>, returning <type>boolean</type> values <literal>FALSE</literal> or
an error is generated if it yields no items. <literal>TRUE</literal> or the value <literal>UNKNOWN</literal> which
is actually an SQL NULL. The default when no <literal>ON ERROR</literal>
clause is specified is to return the <type>boolean</type> value
<literal>FALSE</literal>.
</para> </para>
</listitem>
</itemizedlist>
<para> <para>
Examples: Examples:
</para> </para>
<para> <para>
<literal>select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)')</literal> <literal>JSON_EXISTS(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > $x)' PASSING 2 AS x)</literal>
<returnvalue>t</returnvalue> <returnvalue>t</returnvalue>
</para> </para>
<para> <para>
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)</literal> <literal>JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)</literal>
<returnvalue>f</returnvalue> <returnvalue>f</returnvalue>
</para> </para>
<para> <para>
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)</literal> <literal>JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)</literal>
<returnvalue></returnvalue> <returnvalue></returnvalue>
<programlisting> <programlisting>
ERROR: jsonpath array subscript is out of bounds ERROR: jsonpath array subscript is out of bounds
@ -18731,72 +18747,96 @@ ERROR: jsonpath array subscript is out of bounds
<row> <row>
<entry role="func_table_entry"><para role="func_signature"> <entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_query</primary></indexterm> <indexterm><primary>json_query</primary></indexterm>
<function>json_query</function> ( <synopsis>
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional> <function>JSON_QUERY</function> (
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional> <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
<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>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
<optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </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>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>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</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>) <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>) <returnvalue>jsonb</returnvalue>
</synopsis>
</para> </para>
<itemizedlist>
<listitem>
<para> <para>
Returns the result of applying the SQL/JSON Returns the result of applying the SQL/JSON
<replaceable>path_expression</replaceable> to the <replaceable>path_expression</replaceable> to the
<replaceable>context_item</replaceable> using the <replaceable>context_item</replaceable>.
<literal>PASSING</literal> <replaceable>value</replaceable>s. </para>
</listitem>
<listitem>
<para>
By default, the result is returned as a value of type <type>jsonb</type>,
though the <literal>RETURNING</literal> clause can be used to return
as some other type to which it can be successfully coerced.
</para> </para>
</listitem>
<listitem>
<para> <para>
If the path expression returns multiple SQL/JSON items, it might be If the path expression may return multiple values, it might be necessary
necessary to wrap the result using the <literal>WITH WRAPPER</literal> to wrap those values using the <literal>WITH WRAPPER</literal> clause to
clause to make it a valid JSON string. If the wrapper is make it a valid JSON string, because the default behavior is to not wrap
<literal>UNCONDITIONAL</literal>, an array wrapper will always be them, as if <literal>WITHOUT WRAPPER</literal> were specified. The
applied, even if the returned value is already a single JSON object <literal>WITH WRAPPER</literal> clause is by default taken to mean
or an array. If it is <literal>CONDITIONAL</literal>, it will not be <literal>WITH UNCONDITIONAL WRAPPER</literal>, which means that even a
applied to a single JSON object or an array. single result value will be wrapped. To apply the wrapper only when
<literal>UNCONDITIONAL</literal> is the default. multiple values are present, specify <literal>WITH CONDITIONAL WRAPPER</literal>.
Getting multiple values in result will be treated as an error if
<literal>WITHOUT WRAPPER</literal> is specified.
</para> </para>
</listitem>
<listitem>
<para> <para>
If the result is a scalar string, by default, the returned value will 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 be surrounded by quotes, making it a valid JSON value. It can be made
explicit by specifying <literal>KEEP QUOTES</literal>. Conversely, explicit by specifying <literal>KEEP QUOTES</literal>. Conversely,
quotes can be omitted by specifying <literal>OMIT QUOTES</literal>. quotes can be omitted by specifying <literal>OMIT QUOTES</literal>.
Note that <literal>OMIT QUOTES</literal> cannot be specified when To ensure that the result is a valid JSON value, <literal>OMIT QUOTES</literal>
<literal>WITH WRAPPER</literal> is also specified. cannot be specified when <literal>WITH WRAPPER</literal> is also
specified.
</para> </para>
</listitem>
<listitem>
<para> <para>
The <literal>RETURNING</literal> clause can be used to specify the The <literal>ON EMPTY</literal> clause specifies the behavior if
<replaceable>data_type</replaceable> of the result value. By default, evaluating <replaceable>path_expression</replaceable> yields an empty
the returned value will be of type <type>jsonb</type>. set. The <literal>ON ERROR</literal> clause specifies the behavior
if an error occurs when evaluating <replaceable>path_expression</replaceable>,
when coercing the result value to the <literal>RETURNING</literal> type,
or when evaluating the <literal>ON EMPTY</literal> expression if the
<replaceable>path_expression</replaceable> evaluation returns an empty
set.
</para> </para>
</listitem>
<listitem>
<para> <para>
The <literal>ON EMPTY</literal> clause specifies the behavior if For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,
evaluating <replaceable>path_expression</replaceable> yields no value specifying <literal>ERROR</literal> will cause an error to be thrown with
at all. The default when <literal>ON EMPTY</literal> is not specified the appropriate message. Other options include returning an SQL NULL, an
is to return a null value. empty array (<literal>EMPTY <optional>ARRAY</optional></literal>),
</para> an empty object (<literal>EMPTY OBJECT</literal>), or a user-specified
<para> expression (<literal>DEFAULT</literal> <replaceable>expression</replaceable>)
The <literal>ON ERROR</literal> clause specifies the that can be coerced to jsonb or the type specified in <literal>RETURNING</literal>.
behavior if an error occurs when evaluating The default when <literal>ON EMPTY</literal> or <literal>ON ERROR</literal>
<replaceable>path_expression</replaceable>, including the operation to is not specified is to return an SQL NULL value.
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.
</para> </para>
</listitem>
</itemizedlist>
<para> <para>
Examples: Examples:
</para> </para>
<para> <para>
<literal>select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER)</literal> <literal>JSON_QUERY(jsonb '[1,[2,3],null]', 'lax $[*][$off]' PASSING 1 AS off WITH CONDITIONAL WRAPPER)</literal>
<returnvalue>[3]</returnvalue> <returnvalue>[3]</returnvalue>
</para> </para>
<para> <para>
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES);</literal> <literal>JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES)</literal>
<returnvalue>[1, 2]</returnvalue> <returnvalue>[1, 2]</returnvalue>
</para> </para>
<para> <para>
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR);</literal> <literal>JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR)</literal>
<returnvalue></returnvalue> <returnvalue></returnvalue>
<programlisting> <programlisting>
ERROR: malformed array literal: "[1, 2]" ERROR: malformed array literal: "[1, 2]"
@ -18808,55 +18848,76 @@ DETAIL: Missing "]" after array dimensions.
<row> <row>
<entry role="func_table_entry"><para role="func_signature"> <entry role="func_table_entry"><para role="func_signature">
<indexterm><primary>json_value</primary></indexterm> <indexterm><primary>json_value</primary></indexterm>
<function>json_value</function> ( <synopsis>
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <function>JSON_VALUE</function> (
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional> <replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </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 ERROR</literal> </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>) <returnvalue>text</returnvalue>
</synopsis>
</para> </para>
<itemizedlist>
<listitem>
<para> <para>
Returns the result of applying the SQL/JSON Returns the result of applying the SQL/JSON
<replaceable>path_expression</replaceable> to the <replaceable>path_expression</replaceable> to the
<replaceable>context_item</replaceable> using the <replaceable>context_item</replaceable>.
<literal>PASSING</literal> <replaceable>value</replaceable>s.
</para> </para>
</listitem>
<listitem>
<para> <para>
The extracted value must be a single <acronym>SQL/JSON</acronym> Only use <function>JSON_VALUE()</function> if the extracted value is
scalar item; an error is thrown if that's not the case. If you expect expected to be a single <acronym>SQL/JSON</acronym> scalar item;
that extracted value might be an object or an array, use the getting multiple values will be treated as an error. If you expect that
<function>json_query</function> function instead. extracted value might be an object or an array, use the
<function>JSON_QUERY</function> function instead.
</para> </para>
</listitem>
<listitem>
<para> <para>
The <literal>RETURNING</literal> clause can be used to specify the By default, the result, which must be a single scalar value, is
<replaceable>data_type</replaceable> of the result value. By default, returned as a value of type <type>text</type>, though the
the returned value will be of type <type>text</type>. <literal>RETURNING</literal> clause can be used to return as some
other type to which it can be successfully coerced.
</para> </para>
</listitem>
<listitem>
<para> <para>
The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal> The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
clauses have similar semantics as mentioned in the description of clauses have similar semantics as mentioned in the description of
<function>json_query</function>. <function>JSON_QUERY</function>, except the set of values returned in
lieu of throwing an error is different.
</para> </para>
</listitem>
<listitem>
<para> <para>
Note that scalar strings returned by <function>json_value</function> Note that scalar strings returned by <function>JSON_VALUE</function>
always have their quotes removed, equivalent to specifying always have their quotes removed, equivalent to specifying
<literal>OMIT QUOTES</literal> in <function>json_query</function>. <literal>OMIT QUOTES</literal> in <function>JSON_QUERY</function>.
</para> </para>
</listitem>
</itemizedlist>
<para> <para>
Examples: Examples:
</para> </para>
<para> <para>
<literal>select json_value(jsonb '"123.45"', '$' RETURNING float)</literal> <literal>JSON_VALUE(jsonb '"123.45"', '$' RETURNING float)</literal>
<returnvalue>123.45</returnvalue> <returnvalue>123.45</returnvalue>
</para> </para>
<para> <para>
<literal>select json_value(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI&nbsp;YYYY-MM-DD")' RETURNING date)</literal> <literal>JSON_VALUE(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI&nbsp;YYYY-MM-DD")' RETURNING date)</literal>
<returnvalue>2015-02-01</returnvalue> <returnvalue>2015-02-01</returnvalue>
</para> </para>
<para> <para>
<literal>select json_value(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)</literal> <literal>JSON_VALUE(jsonb '[1,2]', 'strict $[$off]' PASSING 1 as off)</literal>
<returnvalue>2</returnvalue>
</para>
<para>
<literal>JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)</literal>
<returnvalue>9</returnvalue> <returnvalue>9</returnvalue>
</para></entry> </para>
</entry>
</row> </row>
</tbody> </tbody>
</tgroup> </tgroup>
@ -18871,6 +18932,14 @@ DETAIL: Missing "]" after array dimensions.
clause. clause.
</para> </para>
</note> </note>
<note>
<para>
<function>JSON_VALUE()</function> returns an SQL NULL if
<replaceable>path_expression</replaceable> returns a JSON
<literal>null</literal>, whereas <function>JSON_QUERY()</function> returns
the JSON <literal>null</literal> as is.
</para>
</note>
</sect2> </sect2>
<sect2 id="functions-sqljson-table"> <sect2 id="functions-sqljson-table">

Write Preview
Loading…
Cancel
Save