Skip to content

Commit 6185c97

Browse files
amitlanamitlan
committed
Add SQL/JSON query functions
This introduces the following SQL/JSON functions for querying JSON data using jsonpath expressions: JSON_EXISTS(), which can be used to apply a jsonpath expression to a JSON value to check if it yields any values. JSON_QUERY(), which can be used to to apply a jsonpath expression to a JSON value to get a JSON object, an array, or a string. There are various options to control whether multi-value result uses array wrappers and whether the singleton scalar strings are quoted or not. JSON_VALUE(), which can be used to apply a jsonpath expression to a JSON value to return a single scalar value, producing an error if it multiple values are matched. Both JSON_VALUE() and JSON_QUERY() functions have options for handling EMPTY and ERROR conditions, which can be used to specify the behavior when no values are matched and when an error occurs during jsonpath evaluation, respectively. Author: Nikita Glukhov <n.gluhov@postgrespro.ru> Author: Teodor Sigaev <teodor@sigaev.ru> Author: Oleg Bartunov <obartunov@gmail.com> Author: Alexander Korotkov <aekorotkov@gmail.com> Author: Andrew Dunstan <andrew@dunslane.net> Author: Amit Langote <amitlangote09@gmail.com> Author: Peter Eisentraut <peter@eisentraut.org> Author: Jian He <jian.universality@gmail.com> Reviewers have included (in no particular order): Andres Freund, Alexander Korotkov, Pavel Stehule, Andrew Alsup, Erik Rijkers, Zihong Yu, Himanshu Upadhyaya, Daniel Gustafsson, Justin Pryzby, Álvaro Herrera, Jian He, Anton A. Melnikov, Nikita Malakhov, Peter Eisentraut, Tomas Vondra Discussion: https://postgr.es/m/cd0bb935-0158-78a7-08b5-904886deac4b@postgrespro.ru Discussion: https://postgr.es/m/20220616233130.rparivafipt6doj3@alap3.anarazel.de Discussion: https://postgr.es/m/abd9b83b-aa66-f230-3d6d-734817f0995d%40postgresql.org Discussion: https://postgr.es/m/CA+HiwqHROpf9e644D8BRqYvaAPmgBZVup-xKMDPk-nd4EpgzHw@mail.gmail.com Discussion: https://postgr.es/m/CA+HiwqE4XTdfb1nW=Ojoy_tQSRhYt-q_kb6i5d4xcKyrLC1Nbg@mail.gmail.com
1 parent a145f42 commit 6185c97

File tree

34 files changed

+4815
-36
lines changed

34 files changed

+4815
-36
lines changed

‎doc/src/sgml/func.sgml‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15488,6 +15488,11 @@ table2-mapping
1548815488
the SQL/JSON path language
1548915489
</para>
1549015490
</listitem>
15491+
<listitem>
15492+
<para>
15493+
the SQL/JSON query functions
15494+
</para>
15495+
</listitem>
1549115496
</itemizedlist>
1549215497
</para>
1549315498

@@ -18616,6 +18621,211 @@ $.* ? (@ like_regex "^\\d+$")
1861618621
</para>
1861718622
</sect3>
1861818623
</sect2>
18624+
18625+
<sect2 id="sqljson-query-functions">
18626+
<title>SQL/JSON Query Functions</title>
18627+
<para>
18628+
SQL/JSON functions <literal>JSON_EXISTS()</literal>,
18629+
<literal>JSON_QUERY()</literal>, and <literal>JSON_VALUE()</literal>
18630+
described in <xref linkend="functions-sqljson-querying"/> can be used
18631+
to query JSON documents. Each of these functions apply a
18632+
<replaceable>path_expression</replaceable> (the query) to a
18633+
<replaceable>context_item</replaceable> (the document); see
18634+
<xref linkend="functions-sqljson-path"/> for more details on what
18635+
<replaceable>path_expression</replaceable> can contain.
18636+
</para>
18637+
18638+
<table id="functions-sqljson-querying">
18639+
<title>SQL/JSON Query Functions</title>
18640+
<tgroup cols="1">
18641+
<thead>
18642+
<row>
18643+
<entry role="func_table_entry"><para role="func_signature">
18644+
Function signature
18645+
</para>
18646+
<para>
18647+
Description
18648+
</para>
18649+
<para>
18650+
Example(s)
18651+
</para></entry>
18652+
</row>
18653+
</thead>
18654+
<tbody>
18655+
<row>
18656+
<entry role="func_table_entry"><para role="func_signature">
18657+
<indexterm><primary>json_exists</primary></indexterm>
18658+
<function>json_exists</function> (
18659+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18660+
<optional> { <literal>TRUE</literal> | <literal>FALSE</literal> |<literal> UNKNOWN</literal> | <literal>ERROR</literal> } <literal>ON ERROR</literal> </optional>)
18661+
</para>
18662+
<para>
18663+
Returns true if the SQL/JSON <replaceable>path_expression</replaceable>
18664+
applied to the <replaceable>context_item</replaceable> using the
18665+
<literal>PASSING</literal> <replaceable>value</replaceable>s yields any
18666+
items.
18667+
</para>
18668+
<para>
18669+
The <literal>ON ERROR</literal> clause specifies the behavior if
18670+
an error occurs; the default is to return the <type>boolean</type>
18671+
<literal>FALSE</literal> value. Note that if the
18672+
<replaceable>path_expression</replaceable> is <literal>strict</literal>
18673+
and <literal>ON ERROR</literal> behavior is <literal>ERROR</literal>,
18674+
an error is generated if it yields no items.
18675+
</para>
18676+
<para>
18677+
Examples:
18678+
</para>
18679+
<para>
18680+
<literal>select json_exists(jsonb '{"key1": [1,2,3]}', 'strict $.key1[*] ? (@ > 2)')</literal>
18681+
<returnvalue>t</returnvalue>
18682+
</para>
18683+
<para>
18684+
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'lax $.a[5]' ERROR ON ERROR)</literal>
18685+
<returnvalue>f</returnvalue>
18686+
</para>
18687+
<para>
18688+
<literal>select json_exists(jsonb '{"a": [1,2,3]}', 'strict $.a[5]' ERROR ON ERROR)</literal>
18689+
<returnvalue></returnvalue>
18690+
<programlisting>
18691+
ERROR: jsonpath array subscript is out of bounds
18692+
</programlisting>
18693+
</para></entry>
18694+
</row>
18695+
<row>
18696+
<entry role="func_table_entry"><para role="func_signature">
18697+
<indexterm><primary>json_query</primary></indexterm>
18698+
<function>json_query</function> (
18699+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable> <optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18700+
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> <optional> <literal>FORMAT JSON</literal> <optional> <literal>ENCODING UTF8</literal> </optional> </optional> </optional>
18701+
<optional> { <literal>WITHOUT</literal> | <literal>WITH</literal> { <literal>CONDITIONAL</literal> | <optional><literal>UNCONDITIONAL</literal></optional> } } <optional> <literal>ARRAY</literal> </optional> <literal>WRAPPER</literal> </optional>
18702+
<optional> { <literal>KEEP</literal> | <literal>OMIT</literal> } <literal>QUOTES</literal> <optional> <literal>ON SCALAR STRING</literal> </optional> </optional>
18703+
<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>
18704+
<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>)
18705+
</para>
18706+
<para>
18707+
Returns the result of applying the SQL/JSON
18708+
<replaceable>path_expression</replaceable> to the
18709+
<replaceable>context_item</replaceable> using the
18710+
<literal>PASSING</literal> <replaceable>value</replaceable>s.
18711+
</para>
18712+
<para>
18713+
If the path expression returns multiple SQL/JSON items, it might be
18714+
necessary to wrap the result using the <literal>WITH WRAPPER</literal>
18715+
clause to make it a valid JSON string. If the wrapper is
18716+
<literal>UNCONDITIONAL</literal>, an array wrapper will always be
18717+
applied, even if the returned value is already a single JSON object
18718+
or an array. If it is <literal>CONDITIONAL</literal>, it will not be
18719+
applied to a single JSON object or an array.
18720+
<literal>UNCONDITIONAL</literal> is the default.
18721+
</para>
18722+
<para>
18723+
If the result is a scalar string, by default, the returned value will
18724+
be surrounded by quotes, making it a valid JSON value. It can be made
18725+
explicit by specifying <literal>KEEP QUOTES</literal>. Conversely,
18726+
quotes can be omitted by specifying <literal>OMIT QUOTES</literal>.
18727+
Note that <literal>OMIT QUOTES</literal> cannot be specified when
18728+
<literal>WITH WRAPPER</literal> is also specified.
18729+
</para>
18730+
<para>
18731+
The <literal>RETURNING</literal> clause can be used to specify the
18732+
<replaceable>data_type</replaceable> of the result value. By default,
18733+
the returned value will be of type <type>jsonb</type>.
18734+
</para>
18735+
<para>
18736+
The <literal>ON EMPTY</literal> clause specifies the behavior if
18737+
evaluating <replaceable>path_expression</replaceable> yields no value
18738+
at all. The default when <literal>ON EMPTY</literal> is not specified
18739+
is to return a null value.
18740+
</para>
18741+
<para>
18742+
The <literal>ON ERROR</literal> clause specifies the
18743+
behavior if an error occurs when evaluating
18744+
<replaceable>path_expression</replaceable>, including the operation to
18745+
coerce the result value to the output type, or during the execution of
18746+
<literal>ON EMPTY</literal> behavior (that is caused by empty result
18747+
of <replaceable>path_expression</replaceable> evaluation). The default
18748+
when <literal>ON ERROR</literal> is not specified is to return a null
18749+
value.
18750+
</para>
18751+
<para>
18752+
Examples:
18753+
</para>
18754+
<para>
18755+
<literal>select json_query(jsonb '[1,[2,3],null]', 'lax $[*][1]' WITH CONDITIONAL WRAPPER)</literal>
18756+
<returnvalue>[3]</returnvalue>
18757+
</para>
18758+
<para>
18759+
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' OMIT QUOTES);</literal>
18760+
<returnvalue>[1, 2]</returnvalue>
18761+
</para>
18762+
<para>
18763+
<literal>select json_query(jsonb '{"a": "[1, 2]"}', 'lax $.a' RETURNING int[] OMIT QUOTES ERROR ON ERROR);</literal>
18764+
<returnvalue></returnvalue>
18765+
<programlisting>
18766+
ERROR: malformed array literal: "[1, 2]"
18767+
DETAIL: Missing "]" after array dimensions.
18768+
</programlisting>
18769+
</para>
18770+
</entry>
18771+
</row>
18772+
<row>
18773+
<entry role="func_table_entry"><para role="func_signature">
18774+
<indexterm><primary>json_value</primary></indexterm>
18775+
<function>json_value</function> (
18776+
<replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
18777+
<optional> <literal>PASSING</literal> { <replaceable>value</replaceable> <literal>AS</literal> <replaceable>varname</replaceable> } <optional>, ...</optional></optional>
18778+
<optional> <literal>RETURNING</literal> <replaceable>data_type</replaceable> </optional>
18779+
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON EMPTY</literal> </optional>
18780+
<optional> { <literal>ERROR</literal> | <literal>NULL</literal> | <literal>DEFAULT</literal> <replaceable>expression</replaceable> } <literal>ON ERROR</literal> </optional>)
18781+
</para>
18782+
<para>
18783+
Returns the result of applying the SQL/JSON
18784+
<replaceable>path_expression</replaceable> to the
18785+
<replaceable>context_item</replaceable> using the
18786+
<literal>PASSING</literal> <replaceable>value</replaceable>s.
18787+
</para>
18788+
<para>
18789+
The extracted value must be a single <acronym>SQL/JSON</acronym>
18790+
scalar item; an error is thrown if that's not the case. If you expect
18791+
that extracted value might be an object or an array, use the
18792+
<function>json_query</function> function instead.
18793+
</para>
18794+
<para>
18795+
The <literal>RETURNING</literal> clause can be used to specify the
18796+
<replaceable>data_type</replaceable> of the result value. By default,
18797+
the returned value will be of type <type>text</type>.
18798+
</para>
18799+
<para>
18800+
The <literal>ON ERROR</literal> and <literal>ON EMPTY</literal>
18801+
clauses have similar semantics as mentioned in the description of
18802+
<function>json_query</function>.
18803+
</para>
18804+
<para>
18805+
Note that scalar strings returned by <function>json_value</function>
18806+
always have their quotes removed, equivalent to specifying
18807+
<literal>OMIT QUOTES</literal> in <function>json_query</function>.
18808+
</para>
18809+
<para>
18810+
Examples:
18811+
</para>
18812+
<para>
18813+
<literal>select json_value(jsonb '"123.45"', '$' RETURNING float)</literal>
18814+
<returnvalue>123.45</returnvalue>
18815+
</para>
18816+
<para>
18817+
<literal>select json_value(jsonb '"03:04 2015-02-01"', '$.datetime("HH24:MI&nbsp;YYYY-MM-DD")' RETURNING date)</literal>
18818+
<returnvalue>2015-02-01</returnvalue>
18819+
</para>
18820+
<para>
18821+
<literal>select json_value(jsonb '[1,2]', 'strict $[*]' DEFAULT 9 ON ERROR)</literal>
18822+
<returnvalue>9</returnvalue>
18823+
</para></entry>
18824+
</row>
18825+
</tbody>
18826+
</tgroup>
18827+
</table>
18828+
</sect2>
1861918829
</sect1>
1862018830

1862118831
<sect1 id="functions-sequence">

‎src/backend/catalog/sql_features.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -547,15 +547,15 @@ T811 Basic SQL/JSON constructor functions YES
547547
T812 SQL/JSON: JSON_OBJECTAGG YES
548548
T813 SQL/JSON: JSON_ARRAYAGG with ORDER BY YES
549549
T814 Colon in JSON_OBJECT or JSON_OBJECTAGG YES
550-
T821 Basic SQL/JSON query operators NO
550+
T821 Basic SQL/JSON query operators YES
551551
T822 SQL/JSON: IS JSON WITH UNIQUE KEYS predicate YES
552-
T823 SQL/JSON: PASSING clause NO
552+
T823 SQL/JSON: PASSING clause YES
553553
T824 JSON_TABLE: specific PLAN clause NO
554-
T825 SQL/JSON: ON EMPTY and ON ERROR clauses NO
555-
T826 General value expression in ON ERROR or ON EMPTY clauses NO
554+
T825 SQL/JSON: ON EMPTY and ON ERROR clauses YES
555+
T826 General value expression in ON ERROR or ON EMPTY clauses YES
556556
T827 JSON_TABLE: sibling NESTED COLUMNS clauses NO
557-
T828 JSON_QUERY NO
558-
T829 JSON_QUERY: array wrapper options NO
557+
T828 JSON_QUERY YES
558+
T829 JSON_QUERY: array wrapper options YES
559559
T830 Enforcing unique keys in SQL/JSON constructor functions YES
560560
T831 SQL/JSON path language: strict mode YES
561561
T832 SQL/JSON path language: item method YES

0 commit comments

Comments
 (0)