MIME-Version: 1.0
From: Mikhail Dobrinin <mvdobrinin@gmail.com>
Date: Tue, 25 Jan 2022 16:38:05 -0600
Message-ID: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com>
Subject: JSONB docs patch
To: pgsql-hackers@lists.postgresql.org
Content-Type: multipart/mixed; boundary="00000000000000bca905d66fbe80"
Archived-At: <https://www.postgresql.org/message-id/CABKYkG77WX0JhAb7P_YQO2x1-%2BVb_%3DfKxbrgTNbDLo89fjpvLg%40mail.gmail.com>
Precedence: bulk

--00000000000000bca905d66fbe80
Content-Type: multipart/alternative; boundary="00000000000000bca805d66fbe7e"

--00000000000000bca805d66fbe7e
Content-Type: text/plain; charset="UTF-8"

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).

Cheers!
Mikhail Dobrinin

--00000000000000bca805d66fbe7e
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr">Hello,<br><br>I have come across some missing documentatio=
n that I think could benefit the community.<br><br>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=
 `?&amp;` operators. But some JDBC drivers have issues with native queries =
containing these operators (see <a href=3D"https://stackoverflow.com/questi=
ons/38370972/how-do-i-use-postgresql-jsonb-operators-containing-a-question-=
mark-via-jdb">https://stackoverflow.com/questions/38370972/how-do-i-use-pos=
tgresql-jsonb-operators-containing-a-question-mark-via-jdb</a>), so it is u=
seful for users of PG to know the function equivalents of these operators.<=
div><br></div><div>I have attached the patch as an attachment to this email=
. The documentation builds correctly without any lint errors after applying=
 the=C2=A0patch locally. This is my first time contributing, so let me know=
=C2=A0if there is anything else=C2=A0I should do (add to commitfest etc).</=
div><div><br></div><div>Cheers!</div><div>Mikhail Dobrinin</div></div>

--00000000000000bca805d66fbe7e--
--00000000000000bca905d66fbe80
Content-Type: application/octet-stream; name="jsonb-docs-v1.diff"
Content-Disposition: attachment; filename="jsonb-docs-v1.diff"
Content-Transfer-Encoding: base64
Content-ID: <f_kyup6rhh0>
X-Attachment-Id: f_kyup6rhh0

RnJvbSAyZmJkODBkYWZlNzJiMjdmZDYwNDk1MjMyODgxNGRjY2UyOTc3MDRjIE1vbiBTZXAgMTcg
MDA6MDA6MDAgMjAwMQpGcm9tOiBNaWtoYWlsIERvYnJpbmluIDxtdmRvYnJpbmluQGdtYWlsLmNv
bT4KRGF0ZTogVHVlLCAyNSBKYW4gMjAyMiAxNjoxMDo1MyAtMDYwMApTdWJqZWN0OiBbUEFUQ0hd
IEFkZCBkb2N1bWVudGF0aW9uIGZvciBzZXZlcmFsIGpzb25iIGZ1bmN0aW9ucy4KClNldmVyYWwg
ZnVuY3Rpb25zIGxpa2UgYGpzb25iX2V4aXN0c2AsIGBqc29uYl9leGlzdHNfYW55YCwgYGpzb25i
X2V4aXN0c19hbGxgIGhhdmUgZXhpc3RlZCBmb3IgbWFueSBQRyB2ZXJzaW9ucyBidXQgd2VyZSBu
b3QgZG9jdW1lbnRlZC4gVGhleSBhcmUgZXF1aXZhbGVudCB0byBgP2AsIGA/fGAsIGFuZCBgPyZg
IG9wZXJhdG9ycy4gQnV0IHNvbWUgSkRCQyBkcml2ZXJzIGhhdmUgaXNzdWVzIHdpdGggbmF0aXZl
IHF1ZXJpZXMgY29udGFpbmluZyB0aGVzZSBvcGVyYXRvcnMgKHNlZSBodHRwczovL3N0YWNrb3Zl
cmZsb3cuY29tL3F1ZXN0aW9ucy8zODM3MDk3Mi9ob3ctZG8taS11c2UtcG9zdGdyZXNxbC1qc29u
Yi1vcGVyYXRvcnMtY29udGFpbmluZy1hLXF1ZXN0aW9uLW1hcmstdmlhLWpkYiksIHNvIGl0IGlz
IHVzZWZ1bCBmb3IgdXNlcnMgb2YgUEcgdG8ga25vdyB0aGUgZnVuY3Rpb24gZXF1aXZhbGVudHMg
b2YgdGhlc2Ugb3BlcmF0b3JzLgotLS0KIGRvYy9zcmMvc2dtbC9mdW5jLnNnbWwgfCA2NSArKysr
KysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysrKysKIDEgZmlsZSBjaGFuZ2VkLCA2
NSBpbnNlcnRpb25zKCspCgpkaWZmIC0tZ2l0IGEvZG9jL3NyYy9zZ21sL2Z1bmMuc2dtbCBiL2Rv
Yy9zcmMvc2dtbC9mdW5jLnNnbWwKaW5kZXggMGVlNjk3NGYxYy4uZmRjYjlhYmI2ZCAxMDA2NDQK
LS0tIGEvZG9jL3NyYy9zZ21sL2Z1bmMuc2dtbAorKysgYi9kb2Mvc3JjL3NnbWwvZnVuYy5zZ21s
CkBAIC0xNjU5Myw2ICsxNjU5Myw3MSBAQCB0YWJsZTItbWFwcGluZwogICAgICAgICA8cmV0dXJu
dmFsdWU+dDwvcmV0dXJudmFsdWU+CiAgICAgICAgPC9wYXJhPjwvZW50cnk+CiAgICAgICA8L3Jv
dz4KKworICAgICAgPHJvdz4KKyAgICAgICA8ZW50cnkgcm9sZT0iZnVuY190YWJsZV9lbnRyeSI+
PHBhcmEgcm9sZT0iZnVuY19zaWduYXR1cmUiPgorICAgICAgICA8aW5kZXh0ZXJtPgorICAgICAg
ICAgPHByaW1hcnk+anNvbmJfZXhpc3RzPC9wcmltYXJ5PgorICAgICAgICA8L2luZGV4dGVybT4K
KyAgICAgICAgPGZ1bmN0aW9uPmpzb25iX2V4aXN0czwvZnVuY3Rpb24+ICggPHR5cGU+anNvbmI8
L3R5cGU+ICkKKyAgICAgICAgPHJldHVybnZhbHVlPmJvb2xlYW48L3JldHVybnZhbHVlPgorICAg
ICAgIDwvcGFyYT4KKyAgICAgICA8cGFyYT4KKyAgICAgICAgQ2hlY2tzIGlmIHRoZSB0ZXh0IHN0
cmluZyBleGlzdHMgYXMgYSB0b3AtbGV2ZWwga2V5IG9yIGFycmF5IGVsZW1lbnQgd2l0aGluIHRo
ZSBKU09OIHZhbHVlLgorICAgICAgICAoVGhpcyBpcyBmdW5jdGlvbmFsbHkgZXF1aXZhbGVudCB0
byB0aGUganNvbmIgPGxpdGVyYWw+PzwvbGl0ZXJhbD4KKyAgICAgICAgb3BlcmF0b3IsIGJ1dCBt
YXkgYmUgdXNlZnVsIHRvIGNhbGwgYXMgYSBmdW5jdGlvbiBpbiBzb21lIGNhc2VzLCBsaWtlIHdo
ZW4gd29ya2luZyB3aXRoIEpEQkMgcHJvdG9jb2wuKQorICAgICAgIDwvcGFyYT4KKyAgICAgICA8
cGFyYT4KKyAgICAgICAgPGxpdGVyYWw+anNvbmJfZXhpc3RzKCd7ImEiOjEsICJiIjoyfSc6Ompz
b25iLCAnYicpPC9saXRlcmFsPgorICAgICAgICA8cmV0dXJudmFsdWU+dDwvcmV0dXJudmFsdWU+
CisgICAgICAgPC9wYXJhPgorICAgICAgIDxwYXJhPgorICAgICAgICA8bGl0ZXJhbD5qc29uYl9l
eGlzdHMoJ1siYSIsImIiXSc6Ompzb25iLCAnYicpPC9saXRlcmFsPgorICAgICAgICA8cmV0dXJu
dmFsdWU+dDwvcmV0dXJudmFsdWU+CisgICAgICAgPC9wYXJhPjwvZW50cnk+CisgICAgICA8L3Jv
dz4KKworICAgICAgPHJvdz4KKyAgICAgICA8ZW50cnkgcm9sZT0iZnVuY190YWJsZV9lbnRyeSI+
PHBhcmEgcm9sZT0iZnVuY19zaWduYXR1cmUiPgorICAgICAgICA8aW5kZXh0ZXJtPgorICAgICAg
ICAgPHByaW1hcnk+anNvbmJfZXhpc3RzX2FueTwvcHJpbWFyeT4KKyAgICAgICAgPC9pbmRleHRl
cm0+CisgICAgICAgIDxmdW5jdGlvbj5qc29uYl9leGlzdHNfYW55PC9mdW5jdGlvbj4gKCA8dHlw
ZT5qc29uYjwvdHlwZT4gKQorICAgICAgICA8cmV0dXJudmFsdWU+Ym9vbGVhbjwvcmV0dXJudmFs
dWU+CisgICAgICAgPC9wYXJhPgorICAgICAgIDxwYXJhPgorICAgICAgICBDaGVja3MgaWYgYW55
IG9mIHRoZSBzdHJpbmdzIGluIHRoZSB0ZXh0IGFycmF5IGV4aXN0IGFzIHRvcC1sZXZlbCBrZXlz
IG9yIGFycmF5IGVsZW1lbnRzIHdpdGhpbiB0aGUgCisgICAgICAgIEpTT04gdmFsdWUuIChUaGlz
IGlzIGZ1bmN0aW9uYWxseSBlcXVpdmFsZW50IHRvIHRoZSBqc29uYiA8bGl0ZXJhbD4/fDwvbGl0
ZXJhbD4KKyAgICAgICAgb3BlcmF0b3IsIGJ1dCBtYXkgYmUgdXNlZnVsIHRvIGNhbGwgYXMgYSBm
dW5jdGlvbiBpbiBzb21lIGNhc2VzLCBsaWtlIHdoZW4gd29ya2luZyB3aXRoIEpEQkMgcHJvdG9j
b2wuKQorICAgICAgIDwvcGFyYT4KKyAgICAgICA8cGFyYT4KKyAgICAgICAgPGxpdGVyYWw+anNv
bmJfZXhpc3RzX2FueSgneyJhIjoxLCAiYiI6MiwgImMiOjN9Jzo6anNvbmIsIGFycmF5WydiJywg
J2QnXSk8L2xpdGVyYWw+CisgICAgICAgIDxyZXR1cm52YWx1ZT50PC9yZXR1cm52YWx1ZT4KKyAg
ICAgICA8L3BhcmE+PC9lbnRyeT4KKyAgICAgIDwvcm93PgorCisgICAgICA8cm93PgorICAgICAg
IDxlbnRyeSByb2xlPSJmdW5jX3RhYmxlX2VudHJ5Ij48cGFyYSByb2xlPSJmdW5jX3NpZ25hdHVy
ZSI+CisgICAgICAgIDxpbmRleHRlcm0+CisgICAgICAgICA8cHJpbWFyeT5qc29uYl9leGlzdHNf
YWxsPC9wcmltYXJ5PgorICAgICAgICA8L2luZGV4dGVybT4KKyAgICAgICAgPGZ1bmN0aW9uPmpz
b25iX2V4aXN0c19hbGw8L2Z1bmN0aW9uPiAoIDx0eXBlPmpzb25iPC90eXBlPiApCisgICAgICAg
IDxyZXR1cm52YWx1ZT5ib29sZWFuPC9yZXR1cm52YWx1ZT4KKyAgICAgICA8L3BhcmE+CisgICAg
ICAgPHBhcmE+CisgICAgICAgIENoZWNrcyBpZiBhbGwgb2YgdGhlIHN0cmluZ3MgaW4gdGhlIHRl
eHQgYXJyYXkgZXhpc3QgYXMgdG9wLWxldmVsIGtleXMgb3IgYXJyYXkgZWxlbWVudHMgd2l0aGlu
IHRoZSAKKyAgICAgICAgSlNPTiB2YWx1ZS4gKFRoaXMgaXMgZnVuY3Rpb25hbGx5IGVxdWl2YWxl
bnQgdG8gdGhlIGpzb25iIDxsaXRlcmFsPj8mYW1wOzwvbGl0ZXJhbD4KKyAgICAgICAgb3BlcmF0
b3IsIGJ1dCBtYXkgYmUgdXNlZnVsIHRvIGNhbGwgYXMgYSBmdW5jdGlvbiBpbiBzb21lIGNhc2Vz
LCBsaWtlIHdoZW4gd29ya2luZyB3aXRoIEpEQkMgcHJvdG9jb2wuKQorICAgICAgIDwvcGFyYT4K
KyAgICAgICA8cGFyYT4KKyAgICAgICAgPGxpdGVyYWw+anNvbmJfZXhpc3RzX2FsbCgneyJhIjox
LCAiYiI6MiwgImMiOjN9Jzo6anNvbmIsIGFycmF5WydiJywgJ2QnXSk8L2xpdGVyYWw+CisgICAg
ICAgIDxyZXR1cm52YWx1ZT5mPC9yZXR1cm52YWx1ZT4KKyAgICAgICA8L3BhcmE+CisgICAgICAg
PHBhcmE+CisgICAgICAgIDxsaXRlcmFsPmpzb25iX2V4aXN0c19hbGwoJ3siYSI6MSwgImIiOjIs
ICJjIjozfSc6Ompzb25iLCBhcnJheVsnYicsICdjJ10pPC9saXRlcmFsPgorICAgICAgICA8cmV0
dXJudmFsdWU+dDwvcmV0dXJudmFsdWU+CisgICAgICAgPC9wYXJhPjwvZW50cnk+CisgICAgICA8
L3Jvdz4KICAgICAgPC90Ym9keT4KICAgICA8L3Rncm91cD4KICAgIDwvdGFibGU+Ci0tIAoyLjIw
LjEKCg==
--00000000000000bca905d66fbe80--