fix old confusing JSON example

On 2021.04.03. 14:01 Erik Rijkers <er@xs4all.nl> wrote:

Hello,

Attached is a small but confusing mistake in the json documentation (a @@ instead of @?) that has been there since version 12. (It took me quite some time to figure that out while testing with the recent SQL/JSON patches -- which I initially blamed).

To be applied from 12, 13, and master.

Oops, sent to wrong list.

Let me add some arguments for the change:

The original text is:
--------------------------
Also, GIN index supports @@ and @? operators, which perform jsonpath matching.

SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] ? (@ == "qui")';

--------------------------
So, that gives information on two operators, and then gives one example query for each. Clearly, the second example was meant to illustrate a where-clause with the @? operator.

Small change to prevent great confusion (I'll admit it took me far too long to understand this).

thanks,

Erik Rijkers

On Sat, Apr 03, 2021 at 02:01:38PM +0200, Erik Rijkers wrote:

Attached is a small but confusing mistake in the json documentation
(a @@ instead of @?) that has been there since version 12. (It took
me quite some time to figure that out while testing with the recent
SQL/JSON patches -- which I initially blamed).

Please note that pgsql-committers is the mailing list with emails
generated automatically for each commit done in the main repository.
For anything related to the docs, pgsql-docs is more adapted, so I am
redirecting this thread there.
--
Michael

On Sat, Apr 03, 2021 at 02:28:38PM +0200, Erik Rijkers wrote:

So, that gives information on two operators, and then gives one
example query for each. Clearly, the second example was meant to
illustrate a where-clause with the @? operator.

Small change to prevent great confusion (I'll admit it took me far
too long to understand this).

Once one guesses the definition of the table to use with the sample
data at disposal in the docs, it is easy to see that both queries
should return the same result, but the second one misses the shot and
is corrected as you say. So, applied.

My apologies for the delay.
--
Michael

On Fri, Apr 16, 2021 at 11:00 AM Michael Paquier <michael@paquier.xyz> wrote:

On Sat, Apr 03, 2021 at 02:28:38PM +0200, Erik Rijkers wrote:

So, that gives information on two operators, and then gives one
example query for each. Clearly, the second example was meant to
illustrate a where-clause with the @? operator.

Small change to prevent great confusion (I'll admit it took me far
too long to understand this).

Once one guesses the definition of the table to use with the sample
data at disposal in the docs, it is easy to see that both queries
should return the same result, but the second one misses the shot and
is corrected as you say. So, applied.

My apologies for the delay.

My apologies for missing this. And thank you for taking care!

------
Regards,
Alexander Korotkov

On 2021.04.16. 10:00 Michael Paquier <michael@paquier.xyz> wrote:
On Sat, Apr 03, 2021 at 02:28:38PM +0200, Erik Rijkers wrote:

So, that gives information on two operators, and then gives one
example query for each. Clearly, the second example was meant to
illustrate a where-clause with the @? operator.

Small change to prevent great confusion (I'll admit it took me far
too long to understand this).

Once one guesses the definition of the table to use with the sample
data at disposal in the docs, it is easy to see that both queries
should return the same result, but the second one misses the shot and
is corrected as you say. So, applied.

Great, thank you.

I just happened to use the website-documentation and noticed that there the change is not done: it still has the erroneous line, in the docs of 13 (current), and 12; the docs of 14devel are apparently updated.

That makes me wonder: is there a regular html-docs-update (dayly? weekly?) of doc-bugs of this kind in the website-docs of current and earlier releases?

To be clear, I am talking about the lines below:
'GIN index supports @@ and @? operators'

on pages
https://www.postgresql.org/docs/13/datatype-json.html
https://www.postgresql.org/docs/12/datatype-json.html

where the change that was pushed was to correct the second example from @@ to @?

thanks,

Erik Rijkers

On Tue, Apr 20, 2021 at 09:07:52PM +0200, Erik Rijkers wrote:

I just happened to use the website-documentation and noticed that there the change is not done: it still has the erroneous line, in the docs of 13 (current), and 12; the docs of 14devel are apparently updated.

That makes me wonder: is there a regular html-docs-update (dayly? weekly?) of doc-bugs of this kind in the website-docs of current and earlier releases?

To be clear, I am talking about the lines below:
'GIN index supports @@ and @? operators'

on pages
https://www.postgresql.org/docs/13/datatype-json.html
https://www.postgresql.org/docs/12/datatype-json.html

where the change that was pushed was to correct the second example from @@ to @?

Looking at the doc "HOME", it says:
https://www.postgresql.org/docs/13/index.html
| PostgreSQL 13.2 Documentation

So this seems to be updated for minor releases.

--
Justin

Justin Pryzby <pryzby@telsasoft.com> writes:

On Tue, Apr 20, 2021 at 09:07:52PM +0200, Erik Rijkers wrote:

I just happened to use the website-documentation and noticed that there the change is not done: it still has the erroneous line, in the docs of 13 (current), and 12; the docs of 14devel are apparently updated.

That makes me wonder: is there a regular html-docs-update (dayly? weekly?) of doc-bugs of this kind in the website-docs of current and earlier releases?

Looking at the doc "HOME", it says:
https://www.postgresql.org/docs/13/index.html
| PostgreSQL 13.2 Documentation
So this seems to be updated for minor releases.

Yeah. The website's copy of the devel version of the docs is refreshed
quickly (within a few hours of commit, usually) but released branches
are only updated when there's a release.

regards, tom lane