Skip to content

Commit 42de72f

Browse files
amitlanamitlan
committed
SQL/JSON: Various improvements to SQL/JSON query function docs
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
1 parent 571f7f7 commit 42de72f

File tree

1 file changed

+147
-78
lines changed

1 file changed

+147
-78
lines changed

‎doc/src/sgml/func.sgml‎

Lines changed: 147 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -18665,10 +18665,15 @@ $.* ? (@ like_regex "^\\d+$")
1866518665
<literal>JSON_QUERY()</literal>, and <literal>JSON_VALUE()</literal>
1866618666
described in <xref linkend="functions-sqljson-querying"/> can be used
1866718667
to query JSON documents. Each of these functions apply a
18668-
<replaceable>path_expression</replaceable> (the query) to a
18669-
<replaceable>context_item</replaceable> (the document); see
18668+
<replaceable>path_expression</replaceable> (an SQL/JSON path query) to a
18669+
<replaceable>context_item</replaceable> (the document). See
1867018670
<xref linkend="functions-sqljson-path"/> for more details on what
18671-
<replaceable>path_expression</replaceable> can contain.
18671+
the <replaceable>path_expression</replaceable> can contain. The
18672+
<replaceable>path_expression</replaceable> can also reference variables,
18673+
whose values are specified with their respective names in the
18674+
<literal>PASSING</literal> clause that is supported by each function.
18675+
<replaceable>context_item</replaceable> can be a <type>jsonb</type> value
18676+
or a character string that can be successfully cast to <type>jsonb</type>.
1867218677
</para>
1867318678

1867418679
<table id="functions-sqljson-querying">
@@ -18691,37 +18696,48 @@ $.* ? (@ like_regex "^\\d+$")
1869118696
<row>
1869218697
<entry role="func_table_entry"><para role="func_signature">
1869318698
<indexterm><primary>json_exists</primary></indexterm>
18694-
<function>json_exists</function> (
18695-
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18696-
<optional> { <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>)
18699+
<synopsis>
18700+
<function>JSON_EXISTS</function> (
18701+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
18702+
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18703+
<optional>{ <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>) <returnvalue>boolean</returnvalue>
18704+
</synopsis>
1869718705
</para>
18706+
<itemizedlist>
18707+
<listitem>
1869818708
<para>
1869918709
Returns true if the SQL/JSON <replaceable>path_expression</replaceable>
18700-
applied to the <replaceable>context_item</replaceable> using the
18701-
<literal>PASSING</literal> <replaceable>value</replaceable>s yields any
18702-
items.
18710+
applied to the <replaceable>context_item</replaceable> yields any
18711+
items, false otherwise.
1870318712
</para>
18713+
</listitem>
18714+
<listitem>
1870418715
<para>
1870518716
The <literal>ON ERROR</literal> clause specifies the behavior if
18706-
an error occurs; the default is to return the <type>boolean</type>
18707-
<literal>FALSE</literal> value. Note that if the
18708-
<replaceable>path_expression</replaceable> is <literal>strict</literal>
18709-
and <literal>ON ERROR</literal> behavior is <literal>ERROR</literal>,
18710-
an error is generated if it yields no items.
18717+
an error occurs during <replaceable>path_expression</replaceable>
18718+
evaluation. Specifying <literal>ERROR</literal> will cause an error to
18719+
be thrown with the appropriate message. Other options include
18720+
returning <type>boolean</type> values <literal>FALSE</literal> or
18721+
<literal>TRUE</literal> or the value <literal>UNKNOWN</literal> which
18722+
is actually an SQL NULL. The default when no <literal>ON ERROR</literal>
18723+
clause is specified is to return the <type>boolean</type> value
18724+
<literal>FALSE</literal>.
1871118725
</para>
18726+
</listitem>
18727+
</itemizedlist>
1871218728
<para>
1871318729
Examples:
1871418730
</para>
1871518731
<para>
18716-
<literal>select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)')</literal>
18732+
<literal>JSON_EXISTS(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > $x)' PASSING 2 AS x)</literal>
1871718733
<returnvalue>t</returnvalue>
1871818734
</para>
1871918735
<para>
18720-
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)</literal>
18736+
<literal>JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)</literal>
1872118737
<returnvalue>f</returnvalue>
1872218738
</para>
1872318739
<para>
18724-
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)</literal>
18740+
<literal>JSON_EXISTS(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)</literal>
1872518741
<returnvalue></returnvalue>
1872618742
<programlisting>
1872718743
ERROR: jsonpath array subscript is out of bounds
@@ -18731,72 +18747,96 @@ ERROR: jsonpath array subscript is out of bounds
1873118747
<row>
1873218748
<entry role="func_table_entry"><para role="func_signature">
1873318749
<indexterm><primary>json_query</primary></indexterm>
18734-
<function>json_query</function> (
18735-
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18736-
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
18737-
<optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
18738-
<optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
18739-
<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>
18740-
<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>)
18750+
<synopsis>
18751+
<function>JSON_QUERY</function> (
18752+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
18753+
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18754+
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
18755+
<optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
18756+
<optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
18757+
<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>
18758+
<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>
18759+
</synopsis>
1874118760
</para>
18761+
<itemizedlist>
18762+
<listitem>
1874218763
<para>
1874318764
Returns the result of applying the SQL/JSON
1874418765
<replaceable>path_expression</replaceable> to the
18745-
<replaceable>context_item</replaceable> using the
18746-
<literal>PASSING</literal> <replaceable>value</replaceable>s.
18766+
<replaceable>context_item</replaceable>.
18767+
</para>
18768+
</listitem>
18769+
<listitem>
18770+
<para>
18771+
By default, the result is returned as a value of type <type>jsonb</type>,
18772+
though the <literal>RETURNING</literal> clause can be used to return
18773+
as some other type to which it can be successfully coerced.
1874718774
</para>
18775+
</listitem>
18776+
<listitem>
1874818777
<para>
18749-
If the path expression returns multiple SQL/JSON items, it might be
18750-
necessary to wrap the result using the <literal>WITH WRAPPER</literal>
18751-
clause to make it a valid JSON string. If the wrapper is
18752-
<literal>UNCONDITIONAL</literal>, an array wrapper will always be
18753-
applied, even if the returned value is already a single JSON object
18754-
or an array. If it is <literal>CONDITIONAL</literal>, it will not be
18755-
applied to a single JSON object or an array.
18756-
<literal>UNCONDITIONAL</literal> is the default.
18778+
If the path expression may return multiple values, it might be necessary
18779+
to wrap those values using the <literal>WITH WRAPPER</literal> clause to
18780+
make it a valid JSON string, because the default behavior is to not wrap
18781+
them, as if <literal>WITHOUT WRAPPER</literal> were specified. The
18782+
<literal>WITH WRAPPER</literal> clause is by default taken to mean
18783+
<literal>WITH UNCONDITIONAL WRAPPER</literal>, which means that even a
18784+
single result value will be wrapped. To apply the wrapper only when
18785+
multiple values are present, specify <literal>WITH CONDITIONAL WRAPPER</literal>.
18786+
Getting multiple values in result will be treated as an error if
18787+
<literal>WITHOUT WRAPPER</literal> is specified.
1875718788
</para>
18789+
</listitem>
18790+
<listitem>
1875818791
<para>
1875918792
If the result is a scalar string, by default, the returned value will
1876018793
be surrounded by quotes, making it a valid JSON value. It can be made
1876118794
explicit by specifying <literal>KEEP QUOTES</literal>. Conversely,
1876218795
quotes can be omitted by specifying <literal>OMIT QUOTES</literal>.
18763-
Note that <literal>OMIT QUOTES</literal> cannot be specified when
18764-
<literal>WITH WRAPPER</literal> is also specified.
18796+
To ensure that the result is a valid JSON value, <literal>OMIT QUOTES</literal>
18797+
cannot be specified when <literal>WITH WRAPPER</literal> is also
18798+
specified.
1876518799
</para>
18800+
</listitem>
18801+
<listitem>
1876618802
<para>
18767-
The <literal>RETURNING</literal> clause can be used to specify the
18768-
<replaceable>data_type</replaceable> of the result value. By default,
18769-
the returned value will be of type <type>jsonb</type>.
18803+
The <literal>ON EMPTY</literal> clause specifies the behavior if
18804+
evaluating <replaceable>path_expression</replaceable> yields an empty
18805+
set. The <literal>ON ERROR</literal> clause specifies the behavior
18806+
if an error occurs when evaluating <replaceable>path_expression</replaceable>,
18807+
when coercing the result value to the <literal>RETURNING</literal> type,
18808+
or when evaluating the <literal>ON EMPTY</literal> expression if the
18809+
<replaceable>path_expression</replaceable> evaluation returns an empty
18810+
set.
1877018811
</para>
18812+
</listitem>
18813+
<listitem>
1877118814
<para>
18772-
The <literal>ON EMPTY</literal> clause specifies the behavior if
18773-
evaluating <replaceable>path_expression</replaceable> yields no value
18774-
at all. The default when <literal>ON EMPTY</literal> is not specified
18775-
is to return a null value.
18776-
</para>
18777-
<para>
18778-
The <literal>ON ERROR</literal> clause specifies the
18779-
behavior if an error occurs when evaluating
18780-
<replaceable>path_expression</replaceable>, including the operation to
18781-
coerce the result value to the output type, or during the execution of
18782-
<literal>ON EMPTY</literal> behavior (that is caused by empty result
18783-
of <replaceable>path_expression</replaceable> evaluation). The default
18784-
when <literal>ON ERROR</literal> is not specified is to return a null
18785-
value.
18815+
For both <literal>ON EMPTY</literal> and <literal>ON ERROR</literal>,
18816+
specifying <literal>ERROR</literal> will cause an error to be thrown with
18817+
the appropriate message. Other options include returning an SQL NULL, an
18818+
empty array (<literal>EMPTY <optional>ARRAY</optional></literal>),
18819+
an empty object (<literal>EMPTY OBJECT</literal>), or a user-specified
18820+
expression (<literal>DEFAULT</literal> <replaceable>expression</replaceable>)
18821+
that can be coerced to jsonb or the type specified in <literal>RETURNING</literal>.
18822+
The default when <literal>ON EMPTY</literal> or <literal>ON ERROR</literal>
18823+
is not specified is to return an SQL NULL value.
1878618824
</para>
18825+
</listitem>
18826+
</itemizedlist>
1878718827
<para>
1878818828
Examples:
1878918829
</para>
1879018830
<para>
18791-
<literal>select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER)</literal>
18831+
<literal>JSON_QUERY(jsonb '[1,[2,3],null]', 'lax $[*][$off]' PASSING 1 AS off WITH CONDITIONAL WRAPPER)</literal>
1879218832
<returnvalue>[3]</returnvalue>
1879318833
</para>
1879418834
<para>
18795-
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES);</literal>
18835+
<literal>JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES)</literal>
1879618836
<returnvalue>[1, 2]</returnvalue>
1879718837
</para>
1879818838
<para>
18799-
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR);</literal>
18839+
<literal>JSON_QUERY(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR)</literal>
1880018840
<returnvalue></returnvalue>
1880118841
<programlisting>
1880218842
ERROR: malformed array literal: "[1, 2]"
@@ -18808,55 +18848,76 @@ DETAIL: Missing "]" after array dimensions.
1880818848
<row>
1880918849
<entry role="func_table_entry"><para role="func_signature">
1881018850
<indexterm><primary>json_value</primary></indexterm>
18811-
<function>json_value</function> (
18812-
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
18813-
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18814-
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
18815-
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
18816-
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
18851+
<synopsis>
18852+
<function>JSON_VALUE</function> (
18853+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
18854+
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18855+
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
18856+
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
18857+
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>) <returnvalue>text</returnvalue>
18858+
</synopsis>
1881718859
</para>
18860+
<itemizedlist>
18861+
<listitem>
1881818862
<para>
1881918863
Returns the result of applying the SQL/JSON
1882018864
<replaceable>path_expression</replaceable> to the
18821-
<replaceable>context_item</replaceable> using the
18822-
<literal>PASSING</literal> <replaceable>value</replaceable>s.
18865+
<replaceable>context_item</replaceable>.
1882318866
</para>
18867+
</listitem>
18868+
<listitem>
1882418869
<para>
18825-
The extracted value must be a single <acronym>SQL/JSON</acronym>
18826-
scalar item; an error is thrown if that's not the case. If you expect
18827-
that extracted value might be an object or an array, use the
18828-
<function>json_query</function> function instead.
18870+
Only use <function>JSON_VALUE()</function> if the extracted value is
18871+
expected to be a single <acronym>SQL/JSON</acronym> scalar item;
18872+
getting multiple values will be treated as an error. If you expect that
18873+
extracted value might be an object or an array, use the
18874+
<function>JSON_QUERY</function> function instead.
1882918875
</para>
18876+
</listitem>
18877+
<listitem>
1883018878
<para>
18831-
The <literal>RETURNING</literal> clause can be used to specify the
18832-
<replaceable>data_type</replaceable> of the result value. By default,
18833-
the returned value will be of type <type>text</type>.
18879+
By default, the result, which must be a single scalar value, is
18880+
returned as a value of type <type>text</type>, though the
18881+
<literal>RETURNING</literal> clause can be used to return as some
18882+
other type to which it can be successfully coerced.
1883418883
</para>
18884+
</listitem>
18885+
<listitem>
1883518886
<para>
1883618887
The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
1883718888
clauses have similar semantics as mentioned in the description of
18838-
<function>json_query</function>.
18889+
<function>JSON_QUERY</function>, except the set of values returned in
18890+
lieu of throwing an error is different.
1883918891
</para>
18892+
</listitem>
18893+
<listitem>
1884018894
<para>
18841-
Note that scalar strings returned by <function>json_value</function>
18895+
Note that scalar strings returned by <function>JSON_VALUE</function>
1884218896
always have their quotes removed, equivalent to specifying
18843-
<literal>OMIT QUOTES</literal> in <function>json_query</function>.
18897+
<literal>OMIT QUOTES</literal> in <function>JSON_QUERY</function>.
1884418898
</para>
18899+
</listitem>
18900+
</itemizedlist>
1884518901
<para>
1884618902
Examples:
1884718903
</para>
1884818904
<para>
18849-
<literal>select json_value(jsonb '"123.45"', '$' RETURNING float)</literal>
18905+
<literal>JSON_VALUE(jsonb '"123.45"', '$' RETURNING float)</literal>
1885018906
<returnvalue>123.45</returnvalue>
1885118907
</para>
1885218908
<para>
18853-
<literal>select json_value(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI&nbsp;YYYY-MM-DD")' RETURNING date)</literal>
18909+
<literal>JSON_VALUE(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI&nbsp;YYYY-MM-DD")' RETURNING date)</literal>
1885418910
<returnvalue>2015-02-01</returnvalue>
1885518911
</para>
1885618912
<para>
18857-
<literal>select json_value(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)</literal>
18913+
<literal>JSON_VALUE(jsonb '[1,2]', 'strict $[$off]' PASSING 1 as off)</literal>
18914+
<returnvalue>2</returnvalue>
18915+
</para>
18916+
<para>
18917+
<literal>JSON_VALUE(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)</literal>
1885818918
<returnvalue>9</returnvalue>
18859-
</para></entry>
18919+
</para>
18920+
</entry>
1886018921
</row>
1886118922
</tbody>
1886218923
</tgroup>
@@ -18871,6 +18932,14 @@ DETAIL: Missing "]" after array dimensions.
1887118932
clause.
1887218933
</para>
1887318934
</note>
18935+
<note>
18936+
<para>
18937+
<function>JSON_VALUE()</function> returns an SQL NULL if
18938+
<replaceable>path_expression</replaceable> returns a JSON
18939+
<literal>null</literal>, whereas <function>JSON_QUERY()</function> returns
18940+
the JSON <literal>null</literal> as is.
18941+
</para>
18942+
</note>
1887418943
</sect2>
1887518944

1887618945
<sect2 id="functions-sqljson-table">

0 commit comments

Comments
 (0)