Alexander Korotkov <aekorotkov@gmail.com> writes:
> The patch, which clarifies this situation in the docs is attached.
> I'm going to push it if no objections.
+1, but the English in this seems a bit shaky. Perhaps more
like the attached?
regards, tom lane
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 4342c8e74f..de1b1b6deb 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -16277,6 +16277,24 @@ strict $.track.segments[*].location
</programlisting>
</para>
+ <para>
+ The <literal>.**</literal> accessor can lead to surprising results
+ when using the lax mode. For instance, the following query selects every
+ <literal>HR</literal> value twice:
+<programlisting>
+lax $.**.HR
+</programlisting>
+ This happens because the <literal>.**</literal> accessor selects both
+ the <literal>segments</literal> array and each of its elements, while
+ the <literal>.HR</literal> accessor automatically unwraps arrays when
+ using the lax mode. To avoid surprising results, we recommend using
+ the <literal>.**</literal> accessor only in the strict mode. The
+ following query selects each <literal>HR</literal> value just once:
+<programlisting>
+strict $.**.HR
+</programlisting>
+ </para>
+
</sect3>
<sect3 id="functions-sqljson-path-operators">
