Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nCUvW-0007E5-W6 for pgsql-hackers@arkaria.postgresql.org; Tue, 25 Jan 2022 23:08:39 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.92) (envelope-from ) id 1nCUvU-0003An-Kf for pgsql-hackers@arkaria.postgresql.org; Tue, 25 Jan 2022 23:08:36 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1nCUvU-0003Ae-9Z for pgsql-hackers@lists.postgresql.org; Tue, 25 Jan 2022 23:08:36 +0000 Received: from mail-ua1-x92d.google.com ([2607:f8b0:4864:20::92d]) by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.92) (envelope-from ) id 1nCUvP-0000qb-Fc for pgsql-hackers@lists.postgresql.org; Tue, 25 Jan 2022 23:08:35 +0000 Received: by mail-ua1-x92d.google.com with SMTP id r15so40302313uao.3 for ; Tue, 25 Jan 2022 15:08:31 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=mime-version:references:in-reply-to:from:date:message-id:subject:to :cc; bh=1Qq/ZHZHgZW0Ve/R527mz+NPBOdNTbI4V5c4PvvjgPI=; b=e92glJGfqelQVYDjnHn42YbTZz6PuoCEvM43bjxhohG2/ZyTJG7RLqaAAZdrVQVAed h0vrbG4nGYiltwnE5DBdt1Q7ZtvUtfJg5Cops6JTwLu4hT6fCwQxjfaohoKtoZOFfTLg nIt9CO+BOMVYknqYEAi/ySlfqAGElKF+aGqJhVF9ERIuYFH6AR9xJ5V6b98ufXoDqAAb G600aiM9QsuL207ch35RFy0ArMWkGy6cDpZWDyJdj0NsIkFsClFPs3dG3ZHK10u6J2NZ 5l4s1yCRMrdLxwMDmJUrc51e1g8nlTWD+Ybcx4vxDIgQO+ruifkR0Ue6Fm8qVwW7tCsp vj6Q== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:mime-version:references:in-reply-to:from:date :message-id:subject:to:cc; bh=1Qq/ZHZHgZW0Ve/R527mz+NPBOdNTbI4V5c4PvvjgPI=; b=ol9u+Sw4R+doFKe1YUqfTfJY+g2CYhKb8oFVDGOSOUZLkwpyMIGJWZxuORFJju9jzs RJlSneaze8GQzF/YvGc2g7lOkyvmywsPEDzk6O+NP1KJHpQcS4s8rX09PU4XuCNaF9Cu MV2nJNJh/o0ZKU0JaoU+44kmu7XFaIk3/hceldAiQD3WcCpJHldk4ZXydbTosL1DKpWf XVREY2/NZYuloDe3plxbN/4/TUrcP8Js0k+fwlC25ssrKCvfkEimTg3kgN1T73vp6UZE mxMyAU2jzwKPnv6DZrKHeDQ0RMVryRwBp2XvcyJY1GSSzfUHvhDh4T1wjhSHokD6dtUi /Mbg== X-Gm-Message-State: AOAM530PzeSIgCpWlc2H0TyE1nWk3OnOzyEMNApORESsVc7gQEuSoLju 9u+d5PZWJpCOMd27TgX/1fCTv1Rjd2Jt7Ti18Lg= X-Google-Smtp-Source: ABdhPJzyLilk/dFgglnuKz3v5h91O3J9aYOowU5Odzdvpps9MiznOyYQAMLfkD8DPXXGHGDKYRQahQw1e2V/unb59Go= X-Received: by 2002:a67:d899:: with SMTP id f25mr2168039vsj.37.1643152109314; Tue, 25 Jan 2022 15:08:29 -0800 (PST) MIME-Version: 1.0 References: In-Reply-To: From: "David G. Johnston" Date: Tue, 25 Jan 2022 16:08:12 -0700 Message-ID: Subject: Re: JSONB docs patch To: Mikhail Dobrinin Cc: PostgreSQL Hackers Content-Type: multipart/alternative; boundary="000000000000c9a61105d670299d" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000c9a61105d670299d Content-Type: text/plain; charset="UTF-8" On Tue, Jan 25, 2022 at 3:38 PM Mikhail Dobrinin 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. David J. --000000000000c9a61105d670299d Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
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.

Seve= ral functions like `jsonb_exists`, `jsonb_exists_any`, `jsonb_exists_all` h= ave existed for many PG versions but were not documented. They are equivale= nt to `?`, `?|`, and `?&` operators. But some JDBC drivers have issues = with native queries containing these operators (see https://stackoverflow.c= om/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 fun= ction equivalents of these operators.

I have attached th= e patch as an attachment to this email. The documentation builds correctly = without any lint errors after applying the=C2=A0patch locally. This is my f= irst time contributing, so let me know=C2=A0if there is anything else=C2=A0= I should do (add to commitfest etc).


I'm doubtful that encouraging use of these func= tions for JDBC-users is better than them learning to write queries using th= e proper operator.=C2=A0 The reality is that the usage of indexes depends u= pon operators being used in query text, not function names (unless you defi= ne a functional index, which doesn't happen).=C2=A0 Your SO post says a= s 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 wit= hin) an operator in PostgreSQL.=C2=A0 Since core is not presently using tha= t operator its prohibition should be reasonably simple - though maybe exten= sion authors got too creative?

=
-1 to this patch on the above grounds.=C2=A0 A= s for the patch itself:
The parentheticals you= wrote might be appropriate for a commit message but do not belong in the d= ocumentation.=C2=A0 Mentioning JDBC is simply a no-no; and we don't doc= ument "why" we decided to document something. We also don't g= o around pointing out what functions and operators perform the same behavio= r (mostly because we generally just don't do that, see above).
=
I didn't actually review the material parts of the table.= =C2=A0 Nothing seems obviously incorrect there though.

David J.

--000000000000c9a61105d670299d--