Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 5a7d697

Browse files
committed
Assorted fixes for jsonpath documentation
This commit contains assorted fixes for jsonpath documentation including: grammar fixes, incorrect examples fixes as well as wording improvements. Discussion: https://postgr.es/m/CAA-aLv4VVX%3Db9RK5hkfPXJczqaiTdqO04teW9i0wiQVhdKcqzw%40mail.gmail.com Author: Liudmila Mantrova Reviewed-by: Alexander Korotkov Reported-by: Thom Brown
1 parent f7c830f commit 5a7d697

File tree

2 files changed

+64
-53
lines changed

2 files changed

+64
-53
lines changed

doc/src/sgml/func.sgml

+42-31
Original file line numberDiff line numberDiff line change
@@ -11514,7 +11514,8 @@ table2-mapping
1151411514
from the JSON data, similar to XPath expressions used
1151511515
for SQL access to XML. In <productname>PostgreSQL</productname>,
1151611516
path expressions are implemented as the <type>jsonpath</type>
11517-
data type, described in <xref linkend="datatype-jsonpath"/>.
11517+
data type and can use any elements described in
11518+
<xref linkend="datatype-jsonpath"/>.
1151811519
</para>
1151911520

1152011521
<para>JSON query functions and operators
@@ -11561,7 +11562,7 @@ table2-mapping
1156111562
},
1156211563
{ "location": [ 47.706, 13.2635 ],
1156311564
"start time": "2018-10-14 10:39:21",
11564-
"HR": 130
11565+
"HR": 135
1156511566
} ]
1156611567
}
1156711568
}
@@ -11613,23 +11614,33 @@ table2-mapping
1161311614

1161411615
<para>
1161511616
When defining the path, you can also use one or more
11616-
<firstterm>filter expressions</firstterm>, which work similar to
11617-
the <literal>WHERE</literal> clause in SQL. Each filter expression
11618-
can provide one or more filtering conditions that are applied
11619-
to the result of the path evaluation. Each filter expression must
11620-
be enclosed in parentheses and preceded by a question mark.
11621-
Filter expressions are evaluated from left to right and can be nested.
11622-
The <literal>@</literal> variable denotes the current path evaluation
11623-
result to be filtered, and can be followed by one or more accessor
11624-
operators to define the JSON element by which to filter the result.
11625-
Functions and operators that can be used in the filtering condition
11626-
are listed in <xref linkend="functions-sqljson-filter-ex-table"/>.
11627-
SQL/JSON defines three-valued logic, so the result of the filter
11628-
expression may be <literal>true</literal>, <literal>false</literal>,
11617+
<firstterm>filter expressions</firstterm> that work similar to the
11618+
<literal>WHERE</literal> clause in SQL. A filter expression begins with
11619+
a question mark and provides a condition in parentheses:
11620+
11621+
<programlisting>
11622+
? (<replaceable>condition</replaceable>)
11623+
</programlisting>
11624+
</para>
11625+
11626+
<para>
11627+
Filter expressions must be specified right after the path evaluation step
11628+
to which they are applied. The result of this step is filtered to include
11629+
only those items that satisfy the provided condition. SQL/JSON defines
11630+
three-valued logic, so the condition can be <literal>true</literal>, <literal>false</literal>,
1162911631
or <literal>unknown</literal>. The <literal>unknown</literal> value
11630-
plays the same role as SQL <literal>NULL</literal>. Further path
11632+
plays the same role as SQL <literal>NULL</literal> and can be tested
11633+
for with the <literal>is unknown</literal> predicate. Further path
1163111634
evaluation steps use only those items for which filter expressions
11632-
return true.
11635+
return <literal>true</literal>.
11636+
</para>
11637+
11638+
<para>
11639+
Functions and operators that can be used in filter expressions are listed
11640+
in <xref linkend="functions-sqljson-filter-ex-table"/>. The path
11641+
evaluation result to be filtered is denoted by the <literal>@</literal>
11642+
variable. To refer to a JSON element stored at a lower nesting level,
11643+
add one or more accessor operators after <literal>@</literal>.
1163311644
</para>
1163411645

1163511646
<para>
@@ -11643,8 +11654,8 @@ table2-mapping
1164311654
<para>
1164411655
To get the start time of segments with such values instead, you have to
1164511656
filter out irrelevant segments before returning the start time, so the
11646-
filter is applied to the previous step and the path in the filtering
11647-
condition is different:
11657+
filter expression is applied to the previous step, and the path used
11658+
in the condition is different:
1164811659
<programlisting>
1164911660
'$.track.segments[*] ? (@.HR &gt; 130)."start time"'
1165011661
</programlisting>
@@ -11669,9 +11680,9 @@ table2-mapping
1166911680
</para>
1167011681

1167111682
<para>
11672-
You can also nest filters within each other:
11683+
You can also nest filter expressions within each other:
1167311684
<programlisting>
11674-
'$.track ? (@.segments[*] ? (@.HR &gt; 130)).segments.size()'
11685+
'$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size()'
1167511686
</programlisting>
1167611687
This expression returns the size of the track if it contains any
1167711688
segments with high heart rate values, or an empty sequence otherwise.
@@ -12261,7 +12272,7 @@ table2-mapping
1226112272
<row>
1226212273
<entry><literal>@?</literal></entry>
1226312274
<entry><type>jsonpath</type></entry>
12264-
<entry>Does JSON path returns any item for the specified JSON value?</entry>
12275+
<entry>Does JSON path return any item for the specified JSON value?</entry>
1226512276
<entry><literal>'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'</literal></entry>
1226612277
</row>
1226712278
<row>
@@ -12289,8 +12300,8 @@ table2-mapping
1228912300
<note>
1229012301
<para>
1229112302
The <literal>@?</literal> and <literal>@@</literal> operators suppress
12292-
errors including: lacking object field or array element, unexpected JSON
12293-
item type and numeric errors.
12303+
the following errors: lacking object field or array element, unexpected
12304+
JSON item type, and numeric errors.
1229412305
This behavior might be helpful while searching over JSON document
1229512306
collections of varying structure.
1229612307
</para>
@@ -13146,17 +13157,17 @@ table2-mapping
1314613157
<literal>jsonb_path_query</literal>, <literal>jsonb_path_query_array</literal> and
1314713158
<literal>jsonb_path_query_first</literal>
1314813159
functions have optional <literal>vars</literal> and <literal>silent</literal>
13149-
argument.
13160+
arguments.
1315013161
</para>
1315113162
<para>
13152-
When <literal>vars</literal> argument is specified, it constitutes an object
13153-
contained variables to be substituted into <literal>jsonpath</literal>
13154-
expression.
13163+
If the <literal>vars</literal> argument is specified, it provides an
13164+
object containing named variables to be substituted into a
13165+
<literal>jsonpath</literal> expression.
1315513166
</para>
1315613167
<para>
13157-
When <literal>silent</literal> argument is specified and has
13158-
<literal>true</literal> value, the same errors are suppressed as it is in
13159-
the <literal>@?</literal> and <literal>@@</literal> operators.
13168+
If the <literal>silent</literal> argument is specified and has the
13169+
<literal>true</literal> value, these functions suppress the same errors
13170+
as the <literal>@?</literal> and <literal>@@</literal> operators.
1316013171
</para>
1316113172
</note>
1316213173

doc/src/sgml/json.sgml

+22-22
Original file line numberDiff line numberDiff line change
@@ -815,21 +815,18 @@ SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"tags": ["qu
815815
<literal>.**{<replaceable>level</replaceable>}</literal>
816816
</para>
817817
<para>
818-
<literal>.**{<replaceable>lower_level</replaceable> to
819-
<replaceable>upper_level</replaceable>}</literal>
820-
</para>
821-
<para>
822-
<literal>.**{<replaceable>lower_level</replaceable> to
823-
last}</literal>
818+
<literal>.**{<replaceable>start_level</replaceable> to
819+
<replaceable>end_level</replaceable>}</literal>
824820
</para>
825821
</entry>
826822
<entry>
827823
<para>
828-
Same as <literal>.**</literal>, but with filter over nesting
829-
level of JSON hierarchy. Levels are specified as integers.
830-
Zero level corresponds to current object. This is a
831-
<productname>PostgreSQL</productname> extension of the SQL/JSON
832-
standard.
824+
Same as <literal>.**</literal>, but with a filter over nesting
825+
levels of JSON hierarchy. Nesting levels are specified as integers.
826+
Zero level corresponds to the current object. To access the lowest
827+
nesting level, you can use the <literal>last</literal> keyword.
828+
This is a <productname>PostgreSQL</productname> extension of
829+
the SQL/JSON standard.
833830
</para>
834831
</entry>
835832
</row>
@@ -841,19 +838,22 @@ SELECT jdoc-&gt;'guid', jdoc-&gt;'name' FROM api WHERE jdoc @&gt; '{"tags": ["qu
841838
</entry>
842839
<entry>
843840
<para>
844-
Array element accessor. <literal><replaceable>subscript</replaceable></literal>
845-
might be given in two forms: <literal><replaceable>expr</replaceable></literal>
846-
or <literal><replaceable>lower_expr</replaceable> to <replaceable>upper_expr</replaceable></literal>.
847-
The first form specifies single array element by its index. The second
848-
form specified array slice by the range of indexes. Zero index
849-
corresponds to the first array element.
841+
Array element accessor.
842+
<literal><replaceable>subscript</replaceable></literal> can be
843+
given in two forms: <literal><replaceable>index</replaceable></literal>
844+
or <literal><replaceable>start_index</replaceable> to <replaceable>end_index</replaceable></literal>.
845+
The first form returns a single array element by its index. The second
846+
form returns an array slice by the range of indexes, including the
847+
elements that correspond to the provided
848+
<replaceable>start_index</replaceable> and <replaceable>end_index</replaceable>.
850849
</para>
851850
<para>
852-
An expression in the subscript may be an integer,
853-
numeric expression, or any other <literal>jsonpath</literal> expression
854-
returning single numeric value. The <literal>last</literal> keyword
855-
can be used in the expression denoting the last subscript in an array.
856-
That's helpful for handling arrays of unknown length.
851+
The specified <replaceable>index</replaceable> can be an integer, as
852+
well as an expression returning a single numeric value, which is
853+
automatically cast to integer. Zero index corresponds to the first
854+
array element. You can also use the <literal>last</literal> keyword
855+
to denote the last array element, which is useful for handling arrays
856+
of unknown length.
857857
</para>
858858
</entry>
859859
</row>

0 commit comments

Comments
 (0)