On 6/21/19 8:04 PM, Alexander Korotkov wrote:
On Wed, Jun 19, 2019 at 10:14 PM Alexander Korotkov
<a.korot...@postgrespro.ru> wrote:
While I have no objections to the proposed fixes, I think we can further
improve patch 0003 and the text it refers to.
In attempt to clarify jsonpath docs and address the concern that ? is
hard to trace in the current text, I'd also like to propose patch 0004.
Please see both of them attached.
Thank you for your editing. I'm going to commit them as well.
But I'm going to commit your changes separately from 0003 I've posted
before. Because 0003 fixes factual error, while you're proposing set
of grammar/style fixes.
I made some review of these patches. My notes are following:
<para>
- See also <xref linkend="functions-aggregate"/> for the aggregate
- function <function>json_agg</function> which aggregates record
- values as JSON, and the aggregate function
- <function>json_object_agg</function> which aggregates pairs of values
- into a JSON object, and their <type>jsonb</type> equivalents,
+ See also <xref linkend="functions-aggregate"/> for details on
+ <function>json_agg</function> function that aggregates record
+ values as JSON, <function>json_object_agg</function> function
+ that aggregates pairs of values into a JSON object, and their
<type>jsonb</type> equivalents,
<function>jsonb_agg</function> and <function>jsonb_object_agg</function>.
</para>
This part is not directly related to jsonpath, and it has been there
for a long time. I'd like some native english speaker to review this
change before committing this.
<para>
- Expression inside subscript may consititue an integer,
- numeric expression or any other <literal>jsonpath</literal> expression
- returning single numeric value. The <literal>last</literal> keyword
- can be used in the expression denoting the last subscript in an array.
- That's helpful for handling arrays of unknown length.
+ The specified <replaceable>index</replaceable> can be an integer,
+ as well as a numeric or <literal>jsonpath</literal> expression that
+ returns a single integer value. Zero index corresponds to the first
+ array element. To access the last element in an array, you can use
+ the <literal>last</literal> keyword, which is useful for handling
+ arrays of unknown length.
</para>
I think this part requires more work. Let's see what cases do we have
with examples:
1) Integer: '$.ar[1]'
2) Numeric: '$.ar[1.5]' (converted to integer)
3) Some numeric expression: '$.ar[last - 1]'
4) Arbitrary jsonpath expression: '$.ar[$.ar2.size() + $.num - 2]'
In principle, it not necessary to divide 3 and 4, or divide 1 and 2.
Or we may don't describe cases at all, but just say it's a jsonpath
expression returning numeric, which is converted to integer.
Also, note that we do not necessary *access* last array element with
"last" keyword. "last" keyword denotes index of last element in
expression. But completely different element might be actually
accessed.
------
Alexander Korotkov
Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
Hi Alexander,
Thank you for the catch! Please see the modified version of patch 0004
attached.
As for your comment on patch 0003, since I'm not a native speaker, I can
only refer to a recent discussion in pgsql-docs mailing list that seems
to support my view on a similar issue:
https://www.postgresql.org/message-id/9484.1558050957%40sss.pgh.pa.us
--
Liudmila Mantrova
Technical writer at Postgres Professional: http://www.postgrespro.com
The Russian Postgres Company
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 39ba18d..fa5afc1 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11638,10 +11638,17 @@ table2-mapping
<para>
When defining the path, you can also use one or more
<firstterm>filter expressions</firstterm>, which work similar to
- the <literal>WHERE</literal> clause in SQL. Each filter expression
- can provide one or more filtering conditions that are applied
- to the result of the path evaluation. Each filter expression must
- be enclosed in parentheses and preceded by a question mark.
+ the <literal>WHERE</literal> clause in SQL. A filter expression must
+ be enclosed in parentheses and preceded by a question mark:
+
+ <programlisting>
+? (@ <replaceable>filter</replaceable> ...)
+ </programlisting>
+ </para>
+
+ <para>
+ Each filter expression can provide one or more filters
+ that are applied to the result of the path evaluation.
Filter expressions are evaluated from left to right and can be nested.
The <literal>@</literal> variable denotes the current path evaluation
result to be filtered, and can be followed by one or more accessor
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index daebb4f..0d8e2c6 100644
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -815,21 +815,18 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
<literal>.**{<replaceable>level</replaceable>}</literal>
</para>
<para>
- <literal>.**{<replaceable>lower_level</replaceable> to
- <replaceable>upper_level</replaceable>}</literal>
- </para>
- <para>
- <literal>.**{<replaceable>lower_level</replaceable> to
- last}</literal>
+ <literal>.**{<replaceable>start_level</replaceable> to
+ <replaceable>end_level</replaceable>}</literal>
</para>
</entry>
<entry>
<para>
- Same as <literal>.**</literal>, but with filter over nesting
- level of JSON hierarchy. Levels are specified as integers.
- Zero level corresponds to current object. This is a
- <productname>PostgreSQL</productname> extension of the SQL/JSON
- standard.
+ Same as <literal>.**</literal>, but with a filter over nesting
+ levels of JSON hierarchy. Nesting levels are specified as integers.
+ Zero level corresponds to the current object. To access the lowest
+ nesting level, you can use the <literal>last</literal> keyword.
+ This is a <productname>PostgreSQL</productname> extension of
+ the SQL/JSON standard.
</para>
</entry>
</row>
@@ -841,19 +838,22 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
</entry>
<entry>
<para>
- Array element accessor. <literal><replaceable>subscript</replaceable></literal>
- might be given in two forms: <literal><replaceable>expr</replaceable></literal>
- or <literal><replaceable>lower_expr</replaceable> to <replaceable>upper_expr</replaceable></literal>.
- The first form specifies single array element by its index. The second
- form specified array slice by the range of indexes. Zero index
- corresponds to the first array element.
+ Array element accessor.
+ <literal><replaceable>subscript</replaceable></literal> can be
+ given in two forms: <literal><replaceable>index</replaceable></literal>
+ or <literal><replaceable>start_index</replaceable> to <replaceable>end_index</replaceable></literal>.
+ The first form returns a single array element by its index. The second
+ form returns an array slice by the range of indexes, including the
+ elements that correspond to the provided
+ <replaceable>start_index</replaceable> and <replaceable>end_index</replaceable>.
</para>
<para>
- Expression inside subscript may consititue an integer,
- numeric expression or any other <literal>jsonpath</literal> expression
- returning single numeric value. The <literal>last</literal> keyword
- can be used in the expression denoting the last subscript in an array.
- That's helpful for handling arrays of unknown length.
+ The specified <replaceable>index</replaceable> can be an integer, as
+ well as an expression returning a single numeric value, which is
+ automatically cast to integer. Zero index corresponds to the first
+ array element. You can also use the <literal>last</literal> keyword
+ to denote the last array element, which is useful for handling arrays
+ of unknown length.
</para>
</entry>
</row>
