public inbox for [email protected]  

help / color / mirror / Atom feed

From: David G. Johnston <[email protected]>
To: Mikhail Dobrinin <[email protected]>
Cc: PostgreSQL Hackers <[email protected]>
Subject: Re: JSONB docs patch
Date: Tue, 25 Jan 2022 16:08:12 -0700
Message-ID: <CAKFQuwa72XnA_OOdnBkTwvyxYCkkQWRtZLC1+WuTVndVVcZiPg@mail.gmail.com> (raw)
In-Reply-To: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com>
References: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com>

On Tue, Jan 25, 2022 at 3:38 PM Mikhail Dobrinin <[email protected]>
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-qu...),
> 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.

David J.

view thread (3+ messages)

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: JSONB docs patch
  In-Reply-To: <CAKFQuwa72XnA_OOdnBkTwvyxYCkkQWRtZLC1+WuTVndVVcZiPg@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox