Message-ID: <73d54146-09e5-9a99-a7a8-f523213102d9@dunslane.net>
Date: Wed, 26 Jan 2022 09:49:10 -0500
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101
 Thunderbird/91.2.0
Subject: Re: JSONB docs patch
Content-Language: en-US
To: "David G. Johnston" <david.g.johnston@gmail.com>,
 Mikhail Dobrinin <mvdobrinin@gmail.com>
Cc: PostgreSQL Hackers <pgsql-hackers@lists.postgresql.org>
References: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com>
 <CAKFQuwa72XnA_OOdnBkTwvyxYCkkQWRtZLC1+WuTVndVVcZiPg@mail.gmail.com>
From: Andrew Dunstan <andrew@dunslane.net>
In-Reply-To: <CAKFQuwa72XnA_OOdnBkTwvyxYCkkQWRtZLC1+WuTVndVVcZiPg@mail.gmail.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Archived-At: <https://www.postgresql.org/message-id/73d54146-09e5-9a99-a7a8-f523213102d9%40dunslane.net>
Precedence: bulk


On 1/25/22 18:08, David G. Johnston wrote:
> On Tue, Jan 25, 2022 at 3:38 PM Mikhail Dobrinin
> <mvdobrinin@gmail.com> wrote:
>
>     Hello,
>
>     I have come across some missing documentation that I think could
>     benefit the community.
>
>     Several functions like `jsonb_exists`, `jsonb_exists_any`,
>     `jsonb_exists_all` have existed for many PG versions but were not
>     documented. They are equivalent to `?`, `?|`, and `?&` operators.
>     But some JDBC drivers have issues with native queries containing
>     these operators (see
>     https://stackoverflow.com/questions/38370972/how-do-i-use-postgresql-jsonb-operators-containing-a-question-mark-via-jdb),
>     so it is useful for users of PG to know the function equivalents
>     of these operators.
>
>     I have attached the patch as an attachment to this email. The
>     documentation builds correctly without any lint errors after
>     applying the patch locally. This is my first time contributing, so
>     let me know if there is anything else I should do (add to
>     commitfest etc).
>
>
> I'm doubtful that encouraging use of these functions for JDBC-users is
> better than them learning to write queries using the proper operator. 
> The reality is that the usage of indexes depends upon operators being
> used in query text, not function names (unless you define a functional
> index, which doesn't happen).  Your SO post says as much and does
> mention that ?? is indeed the coding that is required.
>
> What I think we should do in light of this reality, though, is indeed
> prohibit "??" as (or within) an operator in PostgreSQL.  Since core is
> not presently using that operator its prohibition should be reasonably
> simple - though maybe extension authors got too creative?
>
> -1 to this patch on the above grounds.  As for the patch itself:
> The parentheticals you wrote might be appropriate for a commit message
> but do not belong in the documentation.  Mentioning JDBC is simply a
> no-no; and we don't document "why" we decided to document something.
> We also don't go around pointing out what functions and operators
> perform the same behavior (mostly because we generally just don't do
> that, see above).
>
> I didn't actually review the material parts of the table.  Nothing
> seems obviously incorrect there though.
>
>

Yeah. The omission from the docs is not accidental - we generally don't
document the functions underlying operators.

These jsonb operators are not the only ones with '?' in the name -
there's a whole heap of them for geometric types. Are we supposed to
document all those too?

I feel the pain that JDBC users have here. It's a pity there are no
alternative placeholder mechanisms in JDBC. Perl's DBD::Pg, which also
has '?' placeholders, provides a couple of quite workable ways around
the issue.


cheers


andrew


--
Andrew Dunstan
EDB: https://www.enterprisedb.com