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

Commit a5c2f3a

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 Backpatch-through: 12
1 parent 4d71359 commit a5c2f3a

File tree

2 files changed

+64
-53
lines changed

2 files changed

+64
-53
lines changed

doc/src/sgml/func.sgml

Lines changed: 42 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11538,7 +11538,8 @@ table2-mapping
1153811538
from the JSON data, similar to XPath expressions used
1153911539
for SQL access to XML. In <productname>PostgreSQL</productname>,
1154011540
path expressions are implemented as the <type>jsonpath</type>
11541-
data type, described in <xref linkend="datatype-jsonpath"/>.
11541+
data type and can use any elements described in
11542+
<xref linkend="datatype-jsonpath"/>.
1154211543
</para>
1154311544

1154411545
<para>JSON query functions and operators
@@ -11585,7 +11586,7 @@ table2-mapping
1158511586
},
1158611587
{ "location": [ 47.706, 13.2635 ],
1158711588
"start time": "2018-10-14 10:39:21",
11588-
"HR": 130
11589+
"HR": 135
1158911590
} ]
1159011591
}
1159111592
}
@@ -11637,23 +11638,33 @@ table2-mapping
1163711638

1163811639
<para>
1163911640
When defining the path, you can also use one or more
11640-
<firstterm>filter expressions</firstterm>, which work similar to
11641-
the <literal>WHERE</literal> clause in SQL. Each filter expression
11642-
can provide one or more filtering conditions that are applied
11643-
to the result of the path evaluation. Each filter expression must
11644-
be enclosed in parentheses and preceded by a question mark.
11645-
Filter expressions are evaluated from left to right and can be nested.
11646-
The <literal>@</literal> variable denotes the current path evaluation
11647-
result to be filtered, and can be followed by one or more accessor
11648-
operators to define the JSON element by which to filter the result.
11649-
Functions and operators that can be used in the filtering condition
11650-
are listed in <xref linkend="functions-sqljson-filter-ex-table"/>.
11651-
SQL/JSON defines three-valued logic, so the result of the filter
11652-
expression may be <literal>true</literal>, <literal>false</literal>,
11641+
<firstterm>filter expressions</firstterm> that work similar to the
11642+
<literal>WHERE</literal> clause in SQL. A filter expression begins with
11643+
a question mark and provides a condition in parentheses:
11644+
11645+
<programlisting>
11646+
? (<replaceable>condition</replaceable>)
11647+
</programlisting>
11648+
</para>
11649+
11650+
<para>
11651+
Filter expressions must be specified right after the path evaluation step
11652+
to which they are applied. The result of this step is filtered to include
11653+
only those items that satisfy the provided condition. SQL/JSON defines
11654+
three-valued logic, so the condition can be <literal>true</literal>, <literal>false</literal>,
1165311655
or <literal>unknown</literal>. The <literal>unknown</literal> value
11654-
plays the same role as SQL <literal>NULL</literal>. Further path
11656+
plays the same role as SQL <literal>NULL</literal> and can be tested
11657+
for with the <literal>is unknown</literal> predicate. Further path
1165511658
evaluation steps use only those items for which filter expressions
11656-
return true.
11659+
return <literal>true</literal>.
11660+
</para>
11661+
11662+
<para>
11663+
Functions and operators that can be used in filter expressions are listed
11664+
in <xref linkend="functions-sqljson-filter-ex-table"/>. The path
11665+
evaluation result to be filtered is denoted by the <literal>@</literal>
11666+
variable. To refer to a JSON element stored at a lower nesting level,
11667+
add one or more accessor operators after <literal>@</literal>.
1165711668
</para>
1165811669

1165911670
<para>
@@ -11667,8 +11678,8 @@ table2-mapping
1166711678
<para>
1166811679
To get the start time of segments with such values instead, you have to
1166911680
filter out irrelevant segments before returning the start time, so the
11670-
filter is applied to the previous step and the path in the filtering
11671-
condition is different:
11681+
filter expression is applied to the previous step, and the path used
11682+
in the condition is different:
1167211683
<programlisting>
1167311684
'$.track.segments[*] ? (@.HR &gt; 130)."start time"'
1167411685
</programlisting>
@@ -11693,9 +11704,9 @@ table2-mapping
1169311704
</para>
1169411705

1169511706
<para>
11696-
You can also nest filters within each other:
11707+
You can also nest filter expressions within each other:
1169711708
<programlisting>
11698-
'$.track ? (@.segments[*] ? (@.HR &gt; 130)).segments.size()'
11709+
'$.track ? (exists(@.segments[*] ? (@.HR &gt; 130))).segments.size()'
1169911710
</programlisting>
1170011711
This expression returns the size of the track if it contains any
1170111712
segments with high heart rate values, or an empty sequence otherwise.
@@ -12285,7 +12296,7 @@ table2-mapping
1228512296
<row>
1228612297
<entry><literal>@?</literal></entry>
1228712298
<entry><type>jsonpath</type></entry>
12288-
<entry>Does JSON path returns any item for the specified JSON value?</entry>
12299+
<entry>Does JSON path return any item for the specified JSON value?</entry>
1228912300
<entry><literal>'{"a":[1,2,3,4,5]}'::jsonb @? '$.a[*] ? (@ > 2)'</literal></entry>
1229012301
</row>
1229112302
<row>
@@ -12313,8 +12324,8 @@ table2-mapping
1231312324
<note>
1231412325
<para>
1231512326
The <literal>@?</literal> and <literal>@@</literal> operators suppress
12316-
errors including: lacking object field or array element, unexpected JSON
12317-
item type and numeric errors.
12327+
the following errors: lacking object field or array element, unexpected
12328+
JSON item type, and numeric errors.
1231812329
This behavior might be helpful while searching over JSON document
1231912330
collections of varying structure.
1232012331
</para>
@@ -13170,17 +13181,17 @@ table2-mapping
1317013181
<literal>jsonb_path_query</literal>, <literal>jsonb_path_query_array</literal> and
1317113182
<literal>jsonb_path_query_first</literal>
1317213183
functions have optional <literal>vars</literal> and <literal>silent</literal>
13173-
argument.
13184+
arguments.
1317413185
</para>
1317513186
<para>
13176-
When <literal>vars</literal> argument is specified, it constitutes an object
13177-
contained variables to be substituted into <literal>jsonpath</literal>
13178-
expression.
13187+
If the <literal>vars</literal> argument is specified, it provides an
13188+
object containing named variables to be substituted into a
13189+
<literal>jsonpath</literal> expression.
1317913190
</para>
1318013191
<para>
13181-
When <literal>silent</literal> argument is specified and has
13182-
<literal>true</literal> value, the same errors are suppressed as it is in
13183-
the <literal>@?</literal> and <literal>@@</literal> operators.
13192+
If the <literal>silent</literal> argument is specified and has the
13193+
<literal>true</literal> value, these functions suppress the same errors
13194+
as the <literal>@?</literal> and <literal>@@</literal> operators.
1318413195
</para>
1318513196
</note>
1318613197

doc/src/sgml/json.sgml

Lines changed: 22 additions & 22 deletions
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)