Doc: improve documentation for jsonpath behavior.

Clarify the behavior of jsonpath operators and functions by
describing their two different modes of operation explicitly.
In addition to the SQL-spec behavior, where a path returns
a list of matching items, we have a "predicate check" form
that always returns a single boolean result.  That was mentioned
in only one place, but it seems better to annotate each operator
and function as to which form(s) it takes.  Also improve the
examples by converting them into actual executable SQL with
results, and do a bunch of incidental wordsmithing.

David Wheeler, reviewed by Erik Wienhold, Jian He, and myself

Discussion: https://postgr.es/m/7262A188-59CA-4A8A-AAD7-83D4FF0B9758@justatheory.com
This commit is contained in:
Tom Lane 2024-01-25 11:32:18 -05:00
parent 66ea94e8e6
commit 7014c9a4bb
2 changed files with 271 additions and 120 deletions

View File

@ -15889,6 +15889,9 @@ table2-mapping
</para> </para>
<para> <para>
Does JSON path return any item for the specified JSON value? Does JSON path return any item for the specified JSON value?
(This is useful only with SQL-standard JSON path expressions, not
<link linkend="functions-sqljson-check-expressions">predicate check
expressions</link>, since those always return a value.)
</para> </para>
<para> <para>
<literal>'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'</literal> <literal>'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'</literal>
@ -15903,9 +15906,12 @@ table2-mapping
</para> </para>
<para> <para>
Returns the result of a JSON path predicate check for the Returns the result of a JSON path predicate check for the
specified JSON value. Only the first item of the result is taken into specified JSON value.
account. If the result is not Boolean, then <literal>NULL</literal> (This is useful only
is returned. with <link linkend="functions-sqljson-check-expressions">predicate
check expressions</link>, not SQL-standard JSON path expressions,
since it will return <literal>NULL</literal> if the path result is
not a single boolean value.)
</para> </para>
<para> <para>
<literal>'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'</literal> <literal>'{"a":[1,2,3,4,5]}'::jsonb @@ '$.a[*] > 2'</literal>
@ -17029,6 +17035,9 @@ ERROR: value too long for type character(2)
<para> <para>
Checks whether the JSON path returns any item for the specified JSON Checks whether the JSON path returns any item for the specified JSON
value. value.
(This is useful only with SQL-standard JSON path expressions, not
<link linkend="functions-sqljson-check-expressions">predicate check
expressions</link>, since those always return a value.)
If the <parameter>vars</parameter> argument is specified, it must If the <parameter>vars</parameter> argument is specified, it must
be a JSON object, and its fields provide named values to be be a JSON object, and its fields provide named values to be
substituted into the <type>jsonpath</type> expression. substituted into the <type>jsonpath</type> expression.
@ -17052,8 +17061,12 @@ ERROR: value too long for type character(2)
</para> </para>
<para> <para>
Returns the result of a JSON path predicate check for the specified Returns the result of a JSON path predicate check for the specified
JSON value. Only the first item of the result is taken into account. JSON value.
If the result is not Boolean, then <literal>NULL</literal> is returned. (This is useful only
with <link linkend="functions-sqljson-check-expressions">predicate
check expressions</link>, not SQL-standard JSON path expressions,
since it will either fail or return <literal>NULL</literal> if the
path result is not a single boolean value.)
The optional <parameter>vars</parameter> The optional <parameter>vars</parameter>
and <parameter>silent</parameter> arguments act the same as and <parameter>silent</parameter> arguments act the same as
for <function>jsonb_path_exists</function>. for <function>jsonb_path_exists</function>.
@ -17075,6 +17088,12 @@ ERROR: value too long for type character(2)
<para> <para>
Returns all JSON items returned by the JSON path for the specified Returns all JSON items returned by the JSON path for the specified
JSON value. JSON value.
For SQL-standard JSON path expressions it returns the JSON
values selected from <parameter>target</parameter>.
For <link linkend="functions-sqljson-check-expressions">predicate
check expressions</link> it returns the result of the predicate
check: <literal>true</literal>, <literal>false</literal>,
or <literal>null</literal>.
The optional <parameter>vars</parameter> The optional <parameter>vars</parameter>
and <parameter>silent</parameter> arguments act the same as and <parameter>silent</parameter> arguments act the same as
for <function>jsonb_path_exists</function>. for <function>jsonb_path_exists</function>.
@ -17103,9 +17122,8 @@ ERROR: value too long for type character(2)
<para> <para>
Returns all JSON items returned by the JSON path for the specified Returns all JSON items returned by the JSON path for the specified
JSON value, as a JSON array. JSON value, as a JSON array.
The optional <parameter>vars</parameter> The parameters are the same as
and <parameter>silent</parameter> arguments act the same as for <function>jsonb_path_query</function>.
for <function>jsonb_path_exists</function>.
</para> </para>
<para> <para>
<literal>jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</literal> <literal>jsonb_path_query_array('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</literal>
@ -17123,11 +17141,10 @@ ERROR: value too long for type character(2)
</para> </para>
<para> <para>
Returns the first JSON item returned by the JSON path for the Returns the first JSON item returned by the JSON path for the
specified JSON value. Returns <literal>NULL</literal> if there are no specified JSON value, or <literal>NULL</literal> if there are no
results. results.
The optional <parameter>vars</parameter> The parameters are the same as
and <parameter>silent</parameter> arguments act the same as for <function>jsonb_path_query</function>.
for <function>jsonb_path_exists</function>.
</para> </para>
<para> <para>
<literal>jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</literal> <literal>jsonb_path_query_first('{"a":[1,2,3,4,5]}', '$.a[*] ? (@ >= $min &amp;&amp; @ &lt;= $max)', '{"min":2, "max":4}')</literal>
@ -17266,9 +17283,9 @@ ERROR: value too long for type character(2)
</indexterm> </indexterm>
<para> <para>
SQL/JSON path expressions specify the items to be retrieved SQL/JSON path expressions specify item(s) to be retrieved
from the JSON data, similar to XPath expressions used from a JSON value, similarly to XPath expressions used
for SQL access to XML. In <productname>PostgreSQL</productname>, for access to XML content. In <productname>PostgreSQL</productname>,
path expressions are implemented as the <type>jsonpath</type> path expressions are implemented as the <type>jsonpath</type>
data type and can use any elements described in data type and can use any elements described in
<xref linkend="datatype-jsonpath"/>. <xref linkend="datatype-jsonpath"/>.
@ -17279,6 +17296,8 @@ ERROR: value too long for type character(2)
pass the provided path expression to the <firstterm>path engine</firstterm> pass the provided path expression to the <firstterm>path engine</firstterm>
for evaluation. If the expression matches the queried JSON data, for evaluation. If the expression matches the queried JSON data,
the corresponding JSON item, or set of items, is returned. the corresponding JSON item, or set of items, is returned.
If there is no match, the result will be <literal>NULL</literal>,
<literal>false</literal>, or an error, depending on the function.
Path expressions are written in the SQL/JSON path language Path expressions are written in the SQL/JSON path language
and can include arithmetic expressions and functions. and can include arithmetic expressions and functions.
</para> </para>
@ -17296,18 +17315,20 @@ ERROR: value too long for type character(2)
<para> <para>
To refer to the JSON value being queried (the To refer to the JSON value being queried (the
<firstterm>context item</firstterm>), use the <literal>$</literal> variable <firstterm>context item</firstterm>), use the <literal>$</literal> variable
in the path expression. It can be followed by one or more in the path expression. The first element of a path must always
be <literal>$</literal>. It can be followed by one or more
<link linkend="type-jsonpath-accessors">accessor operators</link>, <link linkend="type-jsonpath-accessors">accessor operators</link>,
which go down the JSON structure level by level to retrieve sub-items which go down the JSON structure level by level to retrieve sub-items
of the context item. Each operator that follows deals with the of the context item. Each accessor operator acts on the
result of the previous evaluation step. result(s) of the previous evaluation step, producing zero, one, or more
output items from each input item.
</para> </para>
<para> <para>
For example, suppose you have some JSON data from a GPS tracker that you For example, suppose you have some JSON data from a GPS tracker that you
would like to parse, such as: would like to parse, such as:
<programlisting> <programlisting>
{ SELECT '{
"track": { "track": {
"segments": [ "segments": [
{ {
@ -17322,68 +17343,100 @@ ERROR: value too long for type character(2)
} }
] ]
} }
} }' AS json \gset
</programlisting> </programlisting>
(The above example can be copied-and-pasted
into <application>psql</application> to set things up for the following
examples. Then <application>psql</application> will
expand <literal>:'json'</literal> into a suitably-quoted string
constant containing the JSON value.)
</para> </para>
<para> <para>
To retrieve the available track segments, you need to use the To retrieve the available track segments, you need to use the
<literal>.<replaceable>key</replaceable></literal> accessor <literal>.<replaceable>key</replaceable></literal> accessor
operator to descend through surrounding JSON objects: operator to descend through surrounding JSON objects, for example:
<programlisting> <screen>
$.track.segments <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments');</userinput>
</programlisting> jsonb_path_query
-----------------------------------------------------------&zwsp;-----------------------------------------------------------&zwsp;---------------------------------------------
[{"HR": 73, "location": [47.763, 13.4034], "start time": "2018-10-14 10:05:14"}, {"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}]
</screen>
</para> </para>
<para> <para>
To retrieve the contents of an array, you typically use the To retrieve the contents of an array, you typically use the
<literal>[*]</literal> operator. For example, <literal>[*]</literal> operator.
the following path will return the location coordinates for all The following example will return the location coordinates for all
the available track segments: the available track segments:
<programlisting> <screen>
$.track.segments[*].location <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*].location');</userinput>
</programlisting> jsonb_path_query
-------------------
[47.763, 13.4034]
[47.706, 13.2635]
</screen>
Here we started with the whole JSON input value (<literal>$</literal>),
then the <literal>.track</literal> accessor selected the JSON object
associated with the <literal>"track"</literal> object key, then
the <literal>.segments</literal> accessor selected the JSON array
associated with the <literal>"segments"</literal> key within that
object, then the <literal>[*]</literal> accessor selected each element
of that array (producing a series of items), then
the <literal>.location</literal> accessor selected the JSON array
associated with the <literal>"location"</literal> key within each of
those objects. In this example, each of those objects had
a <literal>"location"</literal> key; but if any of them did not,
the <literal>.location</literal> accessor would have simply produced no
output for that input item.
</para> </para>
<para> <para>
To return the coordinates of the first segment only, you can To return the coordinates of the first segment only, you can
specify the corresponding subscript in the <literal>[]</literal> specify the corresponding subscript in the <literal>[]</literal>
accessor operator. Recall that JSON array indexes are 0-relative: accessor operator. Recall that JSON array indexes are 0-relative:
<programlisting> <screen>
$.track.segments[0].location <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[0].location');</userinput>
</programlisting> jsonb_path_query
-------------------
[47.763, 13.4034]
</screen>
</para> </para>
<para> <para>
The result of each path evaluation step can be processed The result of each path evaluation step can be processed
by one or more <type>jsonpath</type> operators and methods by one or more of the <type>jsonpath</type> operators and methods
listed in <xref linkend="functions-sqljson-path-operators"/>. listed in <xref linkend="functions-sqljson-path-operators"/>.
Each method name must be preceded by a dot. For example, Each method name must be preceded by a dot. For example,
you can get the size of an array: you can get the size of an array:
<programlisting> <screen>
$.track.segments.size() <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments.size()');</userinput>
</programlisting> jsonb_path_query
------------------
2
</screen>
More examples of using <type>jsonpath</type> operators More examples of using <type>jsonpath</type> operators
and methods within path expressions appear below in and methods within path expressions appear below in
<xref linkend="functions-sqljson-path-operators"/>. <xref linkend="functions-sqljson-path-operators"/>.
</para> </para>
<para> <para>
When defining a path, you can also use one or more A path can also contain
<firstterm>filter expressions</firstterm> that work similarly to the <firstterm>filter expressions</firstterm> that work similarly to the
<literal>WHERE</literal> clause in SQL. A filter expression begins with <literal>WHERE</literal> clause in SQL. A filter expression begins with
a question mark and provides a condition in parentheses: a question mark and provides a condition in parentheses:
<programlisting> <synopsis>
? (<replaceable>condition</replaceable>) ? (<replaceable>condition</replaceable>)
</programlisting> </synopsis>
</para> </para>
<para> <para>
Filter expressions must be written just after the path evaluation step Filter expressions must be written just after the path evaluation step
to which they should apply. The result of that step is filtered to include to which they should apply. The result of that step is filtered to include
only those items that satisfy the provided condition. SQL/JSON defines only those items that satisfy the provided condition. SQL/JSON defines
three-valued logic, so the condition can be <literal>true</literal>, <literal>false</literal>, three-valued logic, so the condition can
produce <literal>true</literal>, <literal>false</literal>,
or <literal>unknown</literal>. The <literal>unknown</literal> value or <literal>unknown</literal>. The <literal>unknown</literal> value
plays the same role as SQL <literal>NULL</literal> and can be tested plays the same role as SQL <literal>NULL</literal> and can be tested
for with the <literal>is unknown</literal> predicate. Further path for with the <literal>is unknown</literal> predicate. Further path
@ -17395,90 +17448,133 @@ $.track.segments.size()
The functions and operators that can be used in filter expressions are The functions and operators that can be used in filter expressions are
listed in <xref linkend="functions-sqljson-filter-ex-table"/>. Within a listed in <xref linkend="functions-sqljson-filter-ex-table"/>. Within a
filter expression, the <literal>@</literal> variable denotes the value filter expression, the <literal>@</literal> variable denotes the value
being filtered (i.e., one result of the preceding path step). You can being considered (i.e., one result of the preceding path step). You can
write accessor operators after <literal>@</literal> to retrieve component write accessor operators after <literal>@</literal> to retrieve component
items. items.
</para> </para>
<para> <para>
For example, suppose you would like to retrieve all heart rate values higher For example, suppose you would like to retrieve all heart rate values higher
than 130. You can achieve this using the following expression: than 130. You can achieve this as follows:
<programlisting> <screen>
$.track.segments[*].HR ? (@ &gt; 130) <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*].HR ? (@ &gt; 130)');</userinput>
</programlisting> jsonb_path_query
------------------
135
</screen>
</para> </para>
<para> <para>
To get the start times of segments with such values, you have to To get the start times of segments with such values, you have to
filter out irrelevant segments before returning the start times, so the filter out irrelevant segments before selecting the start times, so the
filter expression is applied to the previous step, and the path used filter expression is applied to the previous step, and the path used
in the condition is different: in the condition is different:
<programlisting> <screen>
$.track.segments[*] ? (@.HR &gt; 130)."start time" <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.HR &gt; 130)."start time"');</userinput>
</programlisting> jsonb_path_query
-----------------------
"2018-10-14 10:39:21"
</screen>
</para> </para>
<para> <para>
You can use several filter expressions in sequence, if required. For You can use several filter expressions in sequence, if required.
example, the following expression selects start times of all segments that The following example selects start times of all segments that
contain locations with relevant coordinates and high heart rate values: contain locations with relevant coordinates and high heart rate values:
<programlisting> <screen>
$.track.segments[*] ? (@.location[1] &lt; 13.4) ? (@.HR &gt; 130)."start time" <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] &lt; 13.4) ? (@.HR &gt; 130)."start time"');</userinput>
</programlisting> jsonb_path_query
-----------------------
"2018-10-14 10:39:21"
</screen>
</para> </para>
<para> <para>
Using filter expressions at different nesting levels is also allowed. Using filter expressions at different nesting levels is also allowed.
The following example first filters all segments by location, and then The following example first filters all segments by location, and then
returns high heart rate values for these segments, if available: returns high heart rate values for these segments, if available:
<programlisting> <screen>
$.track.segments[*] ? (@.location[1] &lt; 13.4).HR ? (@ &gt; 130) <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*] ? (@.location[1] &lt; 13.4).HR ? (@ &gt; 130)');</userinput>
</programlisting> jsonb_path_query
------------------
135
</screen>
</para> </para>
<para> <para>
You can also nest filter expressions within each other: You can also nest filter expressions within each other.
<programlisting> This example returns the size of the track if it contains any
$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size() segments with high heart rate values, or an empty sequence otherwise:
</programlisting> <screen>
This expression returns the size of the track if it contains any <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size()');</userinput>
segments with high heart rate values, or an empty sequence otherwise. jsonb_path_query
------------------
2
</screen>
</para> </para>
<para> <sect3 id="functions-sqljson-deviations">
<productname>PostgreSQL</productname>'s implementation of the SQL/JSON path <title>Deviations from the SQL Standard</title>
language has the following deviations from the SQL/JSON standard: <para>
</para> <productname>PostgreSQL</productname>'s implementation of the SQL/JSON path
language has the following deviations from the SQL/JSON standard.
</para>
<itemizedlist> <sect4 id="functions-sqljson-check-expressions">
<listitem> <title>Boolean Predicate Check Expressions</title>
<para> <para>
A path expression can be a Boolean predicate, although the SQL/JSON As an extension to the SQL standard,
standard allows predicates only in filters. This is necessary for a <productname>PostgreSQL</productname> path expression can be a
implementation of the <literal>@@</literal> operator. For example, Boolean predicate, whereas the SQL standard allows predicates only within
the following <type>jsonpath</type> expression is valid in filters. While SQL-standard path expressions return the relevant
<productname>PostgreSQL</productname>: element(s) of the queried JSON value, predicate check expressions
<programlisting> return the single three-valued result of the
$.track.segments[*].HR &lt; 70 predicate: <literal>true</literal>,
</programlisting> <literal>false</literal>, or <literal>unknown</literal>.
</para> For example, we could write this SQL-standard filter expression:
</listitem> <screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments ?(@[*].HR &gt; 130)');</userinput>
jsonb_path_query
-----------------------------------------------------------&zwsp;----------------------
{"HR": 135, "location": [47.706, 13.2635], "start time": "2018-10-14 10:39:21"}
</screen>
The similar predicate check expression simply
returns <literal>true</literal>, indicating that a match exists:
<screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', '$.track.segments[*].HR &gt; 130');</userinput>
jsonb_path_query
------------------
true
</screen>
</para>
<listitem> <note>
<para> <para>
There are minor differences in the interpretation of regular Predicate check expressions are required in the
expression patterns used in <literal>like_regex</literal> filters, as <literal>@@</literal> operator (and the
described in <xref linkend="jsonpath-regular-expressions"/>. <function>jsonb_path_match</function> function), and should not be used
</para> with the <literal>@?</literal> operator (or the
</listitem> <function>jsonb_path_exists</function> function).
</itemizedlist> </para>
</note>
</sect4>
<sect3 id="strict-and-lax-modes"> <sect4 id="functions-sqljson-regular-expression-deviation">
<title>Regular Expression Interpretation</title>
<para>
There are minor differences in the interpretation of regular
expression patterns used in <literal>like_regex</literal> filters, as
described in <xref linkend="jsonpath-regular-expressions"/>.
</para>
</sect4>
</sect3>
<sect3 id="functions-sqljson-strict-and-lax-modes">
<title>Strict and Lax Modes</title> <title>Strict and Lax Modes</title>
<para> <para>
When you query JSON data, the path expression may not match the When you query JSON data, the path expression may not match the
actual JSON data structure. An attempt to access a non-existent actual JSON data structure. An attempt to access a non-existent
member of an object or element of an array results in a member of an object or element of an array is defined as a
structural error. SQL/JSON path expressions have two modes structural error. SQL/JSON path expressions have two modes
of handling structural errors: of handling structural errors:
</para> </para>
@ -17488,8 +17584,8 @@ $.track.segments[*].HR &lt; 70
<para> <para>
lax (default) &mdash; the path engine implicitly adapts lax (default) &mdash; the path engine implicitly adapts
the queried data to the specified path. the queried data to the specified path.
Any remaining structural errors are suppressed and converted Any structural errors that cannot be fixed as described below
to empty SQL/JSON sequences. are suppressed, producing no match.
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -17500,15 +17596,15 @@ $.track.segments[*].HR &lt; 70
</itemizedlist> </itemizedlist>
<para> <para>
The lax mode facilitates matching of a JSON document structure and path Lax mode facilitates matching of a JSON document and path
expression if the JSON data does not conform to the expected schema. expression when the JSON data does not conform to the expected schema.
If an operand does not match the requirements of a particular operation, If an operand does not match the requirements of a particular operation,
it can be automatically wrapped as an SQL/JSON array or unwrapped by it can be automatically wrapped as an SQL/JSON array, or unwrapped by
converting its elements into an SQL/JSON sequence before performing converting its elements into an SQL/JSON sequence before performing
this operation. Besides, comparison operators automatically unwrap their the operation. Also, comparison operators automatically unwrap their
operands in the lax mode, so you can compare SQL/JSON arrays operands in lax mode, so you can compare SQL/JSON arrays
out-of-the-box. An array of size 1 is considered equal to its sole element. out-of-the-box. An array of size 1 is considered equal to its sole element.
Automatic unwrapping is not performed only when: Automatic unwrapping is not performed when:
<itemizedlist> <itemizedlist>
<listitem> <listitem>
<para> <para>
@ -17531,41 +17627,96 @@ $.track.segments[*].HR &lt; 70
<para> <para>
For example, when querying the GPS data listed above, you can For example, when querying the GPS data listed above, you can
abstract from the fact that it stores an array of segments abstract from the fact that it stores an array of segments
when using the lax mode: when using lax mode:
<programlisting> <screen>
lax $.track.segments.location <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'lax $.track.segments.location');</userinput>
</programlisting> jsonb_path_query
-------------------
[47.763, 13.4034]
[47.706, 13.2635]
</screen>
</para> </para>
<para> <para>
In the strict mode, the specified path must exactly match the structure of In strict mode, the specified path must exactly match the structure of
the queried JSON document to return an SQL/JSON item, so using this the queried JSON document, so using this path
path expression will cause an error. To get the same result as in expression will cause an error:
the lax mode, you have to explicitly unwrap the <screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments.location');</userinput>
ERROR: jsonpath member accessor can only be applied to an object
</screen>
To get the same result as in lax mode, you have to explicitly unwrap the
<literal>segments</literal> array: <literal>segments</literal> array:
<programlisting> <screen>
strict $.track.segments[*].location <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments[*].location');</userinput>
</programlisting> jsonb_path_query
-------------------
[47.763, 13.4034]
[47.706, 13.2635]
</screen>
</para> </para>
<para> <para>
The <literal>.**</literal> accessor can lead to surprising results The unwrapping behavior of lax mode can lead to surprising results. For
when using the lax mode. For instance, the following query selects every instance, the following query using the <literal>.**</literal> accessor
<literal>HR</literal> value twice: selects every <literal>HR</literal> value twice:
<programlisting> <screen>
lax $.**.HR <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'lax $.**.HR');</userinput>
</programlisting> jsonb_path_query
------------------
73
135
73
135
</screen>
This happens because the <literal>.**</literal> accessor selects both This happens because the <literal>.**</literal> accessor selects both
the <literal>segments</literal> array and each of its elements, while the <literal>segments</literal> array and each of its elements, while
the <literal>.HR</literal> accessor automatically unwraps arrays when the <literal>.HR</literal> accessor automatically unwraps arrays when
using the lax mode. To avoid surprising results, we recommend using using lax mode. To avoid surprising results, we recommend using
the <literal>.**</literal> accessor only in the strict mode. The the <literal>.**</literal> accessor only in strict mode. The
following query selects each <literal>HR</literal> value just once: following query selects each <literal>HR</literal> value just once:
<programlisting> <screen>
strict $.**.HR <prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.**.HR');</userinput>
</programlisting> jsonb_path_query
------------------
73
135
</screen>
</para> </para>
<para>
The unwrapping of arrays can also lead to unexpected results. Consider this
example, which selects all the <literal>location</literal> arrays:
<screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'lax $.track.segments[*].location');</userinput>
jsonb_path_query
-------------------
[47.763, 13.4034]
[47.706, 13.2635]
(2 rows)
</screen>
As expected it returns the full arrays. But applying a filter expression
causes the arrays to be unwrapped to evaluate each item, returning only the
items that match the expression:
<screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'lax $.track.segments[*].location ?(@[*] &gt; 15)');</userinput>
jsonb_path_query
------------------
47.763
47.706
(2 rows)
</screen>
This despite the fact that the full arrays are selected by the path
expression. Use strict mode to restore selecting the arrays:
<screen>
<prompt>=&gt;</prompt> <userinput>select jsonb_path_query(:'json', 'strict $.track.segments[*].location ?(@[*] &gt; 15)');</userinput>
jsonb_path_query
-------------------
[47.763, 13.4034]
[47.706, 13.2635]
(2 rows)
</screen>
</para>
</sect3> </sect3>
<sect3 id="functions-sqljson-path-operators"> <sect3 id="functions-sqljson-path-operators">

View File

@ -513,7 +513,7 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
</programlisting> </programlisting>
For these operators, a GIN index extracts clauses of the form For these operators, a GIN index extracts clauses of the form
<literal><replaceable>accessors_chain</replaceable> <literal><replaceable>accessors_chain</replaceable>
= <replaceable>constant</replaceable></literal> out of == <replaceable>constant</replaceable></literal> out of
the <type>jsonpath</type> pattern, and does the index search based on the <type>jsonpath</type> pattern, and does the index search based on
the keys and values mentioned in these clauses. The accessors chain the keys and values mentioned in these clauses. The accessors chain
may include <literal>.<replaceable>key</replaceable></literal>, may include <literal>.<replaceable>key</replaceable></literal>,