Skip to content

Commit a3fc469

Browse files
author
Nikita Glukhov
committed
Add documentation for IS JSON predicate
1 parent 4b3a5f7 commit a3fc469

File tree

1 file changed

+254
-1
lines changed

1 file changed

+254
-1
lines changed

‎doc/src/sgml/func.sgml‎

Lines changed: 254 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16886,7 +16886,16 @@ $ ? (@ like_regex "^\\d+$")
1688616886
</listitem>
1688716887
</itemizedlist>
1688816888

16889-
<sect3 id="functions-sqljson-producing">
16889+
<para>
16890+
All SQL/JSON functions fall into one of the two groups.
16891+
<link linkend="functions-sqljson-producing">Constructor functions</link>
16892+
generate JSON data from values of SQL types.
16893+
<link linkend="functions-sqljson-querying">Query functions</link>
16894+
evaluate SQL/JSON path language expressions against JSON values
16895+
and produce values of SQL/JSON types, which are converted to SQL types.
16896+
</para>
16897+
16898+
<sect3 id="functions-sqljson-producing">
1689016899
<title>Producing JSON Content</title>
1689116900

1689216901
<para>
@@ -17646,10 +17655,254 @@ FROM films AS f;
1764617655
</sect5>
1764717656
</sect4>
1764817657
</sect3>
17658+
17659+
<sect3 id="functions-sqljson-querying">
17660+
<title>Querying JSON</title>
17661+
17662+
<para>
17663+
SQL/JSON query functions evaluate SQL/JSON path language expressions
17664+
against JSON values, producing values of SQL/JSON types, which are
17665+
converted to SQL types. All SQL/JSON query functions accept several
17666+
common clauses described in <xref linkend="sqljson-common-clauses"/>.
17667+
For details on the SQL/JSON path language,
17668+
see <xref linkend="functions-sqljson-path"/>.
17669+
</para>
17670+
17671+
<itemizedlist>
17672+
<listitem>
17673+
<para>
17674+
<xref linkend="functions-isjson-predicate"/>
17675+
</para>
17676+
</listitem>
17677+
</itemizedlist>
17678+
17679+
<para>
17680+
In some usage examples for these functions,
17681+
the following small table storing some JSON data will be used:
17682+
<programlisting>
17683+
CREATE TABLE my_films (
17684+
js text );
17685+
17686+
INSERT INTO my_films VALUES (
17687+
'{ "favorites" : [
17688+
{ "kind" : "comedy", "films" : [
17689+
{ "title" : "Bananas",
17690+
"director" : "Woody Allen"},
17691+
{ "title" : "The Dinner Game",
17692+
"director" : "Francis Veber" } ] },
17693+
{ "kind" : "horror", "films" : [
17694+
{ "title" : "Psycho",
17695+
"director" : "Alfred Hitchcock" } ] },
17696+
{ "kind" : "thriller", "films" : [
17697+
{ "title" : "Vertigo",
17698+
"director" : "Alfred Hitchcock" } ] },
17699+
{ "kind" : "drama", "films" : [
17700+
{ "title" : "Yojimbo",
17701+
"director" : "Akira Kurosawa" } ] }
17702+
] }');
17703+
</programlisting>
17704+
</para>
17705+
17706+
<refentry id="functions-isjson-predicate">
17707+
<refnamediv>
17708+
<refname>IS JSON</refname>
17709+
<refpurpose>test whether the provided value is valid JSON data</refpurpose>
17710+
</refnamediv>
17711+
17712+
<refsynopsisdiv>
17713+
<synopsis>
17714+
<replaceable class="parameter">expression</replaceable>
17715+
IS [ NOT ] JSON
17716+
[ { VALUE | SCALAR | ARRAY | OBJECT } ]
17717+
[ { WITH | WITHOUT } UNIQUE [ KEYS ] ]
17718+
</synopsis>
17719+
</refsynopsisdiv>
17720+
17721+
<refsect1>
17722+
<title>Description</title>
17723+
17724+
<para>
17725+
<command>IS JSON</command> predicate tests whether the provided value is valid
17726+
<acronym>JSON</acronym> data. If you provide a specific JSON data type as a parameter,
17727+
you can check whether the value belongs to this type.
17728+
You can also use this predicate in the <command>IS NOT JSON</command> form.
17729+
The return values are:
17730+
<itemizedlist>
17731+
<listitem>
17732+
<para>
17733+
<literal>t</literal> if the value satisfies the specified condition.
17734+
</para>
17735+
</listitem>
17736+
<listitem>
17737+
<para>
17738+
<literal>f</literal> if the value does not satisfy the specified condition.
17739+
</para>
17740+
</listitem>
17741+
</itemizedlist>
17742+
</para>
17743+
</refsect1>
17744+
17745+
<refsect1>
17746+
<title>Parameters</title>
17747+
17748+
<variablelist>
17749+
17750+
<varlistentry>
17751+
<term>
17752+
<literal><replaceable class="parameter">expression</replaceable></literal>
17753+
</term>
17754+
<listitem>
17755+
17756+
<para>
17757+
The input clause defining the value to test. You can provide the values
17758+
of <literal>json</literal>, <literal>jsonb</literal>,
17759+
<literal>bytea</literal>, or character string types.
17760+
</para>
17761+
</listitem>
17762+
</varlistentry>
17763+
17764+
<varlistentry>
17765+
<term>
17766+
<literal>VALUE | SCALAR | ARRAY | OBJECT</literal>
17767+
</term>
17768+
<listitem>
17769+
17770+
<para>
17771+
Specifies the <acronym>JSON</acronym> data type to test for:
17772+
<itemizedlist>
17773+
<listitem>
17774+
<para>
17775+
<literal>VALUE</literal> (default) &mdash; any <acronym>JSON</acronym> type.
17776+
</para>
17777+
</listitem>
17778+
<listitem>
17779+
<para>
17780+
<literal>SCALAR</literal> &mdash; <acronym>JSON</acronym> number, string, or boolean.
17781+
</para>
17782+
</listitem>
17783+
<listitem>
17784+
<para>
17785+
<literal>ARRAY</literal> &mdash; <acronym>JSON</acronym> array.
17786+
</para>
17787+
</listitem>
17788+
<listitem>
17789+
<para>
17790+
<literal>OBJECT</literal> &mdash; <acronym>JSON</acronym> object.
17791+
</para>
17792+
</listitem>
17793+
</itemizedlist>
17794+
</para>
17795+
</listitem>
17796+
</varlistentry>
17797+
17798+
<varlistentry>
17799+
<term>
17800+
<literal>{ WITH | WITHOUT } UNIQUE [ KEYS ]</literal>
17801+
</term>
17802+
<listitem>
17803+
<para>Defines whether duplicate keys are allowed:
17804+
<itemizedlist>
17805+
<listitem>
17806+
<para>
17807+
<literal>WITHOUT</literal> (default) &mdash; the
17808+
<acronym>JSON</acronym> object can contain duplicate keys.
17809+
</para>
17810+
</listitem>
17811+
<listitem>
17812+
<para>
17813+
<literal>WITH</literal> &mdash; duplicate keys are not allowed.
17814+
If the input data contains duplicate keys, it is considered to be invalid JSON.
17815+
</para>
17816+
</listitem>
17817+
</itemizedlist>
17818+
Optionally, you can add the <literal>KEYS</literal> keyword for semantic clarity.
17819+
</para>
17820+
</listitem>
17821+
</varlistentry>
17822+
</variablelist>
17823+
17824+
</refsect1>
17825+
17826+
<refsect1>
17827+
<title>Examples</title>
17828+
17829+
<para>
17830+
Compare the result returned by the <function>IS JSON</function>
17831+
predicate for different data types:
17832+
</para>
17833+
<screen>
17834+
SELECT
17835+
js,
17836+
js IS JSON "is json",
17837+
js IS NOT JSON "is not json",
17838+
js IS JSON SCALAR "is scalar",
17839+
js IS JSON OBJECT "is object",
17840+
js IS JSON ARRAY "is array"
17841+
FROM
17842+
(VALUES ('123'), ('"abc"'), ('{"a": "b"}'), ('[1,2]'), ('abc')) foo(js);
17843+
17844+
js | is json | is not json | is scalar | is object | is array
17845+
------------+---------+-------------+-----------+-----------|-------------
17846+
123 | t | f | t | f | f
17847+
"abc" | t | f | t | f | f
17848+
{"a": "b"} | t | f | f | t | f
17849+
[1,2] | t | f | f | f | t
17850+
abc | f | t | f | f | f
17851+
(5 rows)
17852+
</screen>
17853+
</refsect1>
17854+
</refentry>
17855+
17856+
17857+
</sect3>
1764917858

1765017859
<sect3 id="sqljson-common-clauses">
1765117860
<title>SQL/JSON Common Clauses</title>
1765217861

17862+
<sect4 id="sqljson-input-clause">
17863+
<title>SQL/JSON Input Clause</title>
17864+
17865+
<variablelist>
17866+
<varlistentry>
17867+
<term>
17868+
<literal><replaceable>context_item</replaceable>, <replaceable>path_expression</replaceable>
17869+
[ PASSING { <replaceable>value</replaceable> AS <replaceable>varname</replaceable> } [, ...]]</literal>
17870+
</term>
17871+
<listitem>
17872+
<para>
17873+
The input clause specifies the JSON data to query and
17874+
the exact query path to be passed to SQL/JSON query functions:
17875+
</para>
17876+
<itemizedlist>
17877+
<listitem>
17878+
<para>
17879+
The <replaceable>context_item</replaceable> is the JSON data to query.
17880+
</para>
17881+
</listitem>
17882+
<listitem>
17883+
<para>
17884+
The <replaceable>path_expression</replaceable> is an SQL/JSON path
17885+
expression that specifies the items to be retrieved from the JSON
17886+
data. For details on path expression syntax, see
17887+
<xref linkend="functions-sqljson-path"/>.
17888+
</para>
17889+
</listitem>
17890+
<listitem>
17891+
<para>
17892+
The optional <command>PASSING</command> clause provides the values for
17893+
the named variables used in the SQL/JSON path expression.
17894+
</para>
17895+
</listitem>
17896+
</itemizedlist>
17897+
<para>
17898+
The input clause is common for all SQL/JSON query functions.
17899+
</para>
17900+
</listitem>
17901+
</varlistentry>
17902+
</variablelist>
17903+
17904+
</sect4>
17905+
1765317906
<sect4 id="sqljson-output-clause">
1765417907
<title>SQL/JSON Output Clause</title>
1765517908

0 commit comments

Comments
 (0)