Re: ​jsonb @@ jsonpath operator doc: ​Only the first item of the result is taken into account

Erik Wienhold <ewie(at)ewie(dot)name> writes:
> What do you mean? I responded to the OP's question. It's not a suggestion
> to update the docs. Obviously it's quite a mouthful and needs to be boiled
> down for the docs. Any suggestions?

At least for the example at hand, I think a good part of the confusion
stems from the undocumented way that the boolean test operator works.
As far as I can find, the only mention of that is in Section 9.16.2 [1],
which says (just before 9.16.2.1):

PostgreSQL's implementation of the SQL/JSON path language has the
following deviations from the SQL/JSON standard:

A path expression can be a Boolean predicate, although the
SQL/JSON standard allows predicates only in filters. This is
necessary for implementation of the @@ operator. For example, the
following jsonpath expression is valid in PostgreSQL:

$.track.segments[*].HR < 70

That is a complete documentation fail if you ask me, because it doesn't
explain what the construct actually does, nor is there anyplace else
where you could find that out, not even the SQL standard.

So I'd start by fleshing that out, and then see what to do with the
description of the @@ operator (and the equivalent jsonb_path_match
function). Some more examples for those might help.

regards, tom lane

[1] https://www.postgresql.org/docs/devel/functions-json.html#FUNCTIONS-SQLJSON-PATH