Subject: Missing jsonb_ ... functions on DOCs

From: Marcos Pegoraro <[email-masked]>
Date: Sun, 10 May 2026 13:49:51 -0300

None of these functions are documented, Is this intentional ?
If not, how can these functions be there ?
An additional table right after operators ?
Just a comment on the correspondent operator ?

-- jsonb_exists - corresponds to ? operator
select jsonb_exists('{"a":null, "b":"qq"}', 'a');
select '{"a":null, "b":"qq"}'::jsonb ? 'a';

-- jsonb_exists_any - corresponds to ?| operator
select jsonb_exists_any('{"a":null, "b":"qq"}', ARRAY['a','c']);
select '{"a":null, "b":"qq"}'::jsonb ?| ARRAY['a','c'];

-- jsonb_exists_all - corresponds to ?& operator
select jsonb_exists_all('{"a":null, "b":"qq"}', ARRAY['a','b']);
select '{"a":null, "b":"qq"}'::jsonb ?& ARRAY['a','b'];

-- jsonb_contains - corresponds to @> operator
select jsonb_contains('{"a":null, "b":"qq"}', '{"b":"qq"}');
select '{"a":null, "b":"qq"}'::jsonb @> '{"b":"qq"}';

-- jsonb_contained - corresponds to <@ operator
select jsonb_contained('{"b":"qq"}','{"a":null, "b":"qq"}');
select '{"b":"qq"}' <@ '{"a":null, "b":"qq"}'::jsonb;

-- jsonb_concat - corresponds to || operator
select jsonb_concat('{"b":"qq"}','{"a":null}');
select '{"b":"qq"}'::jsonb || '{"a":null}'::jsonb;

-- jsonb_delete - corresponds to - operator
select jsonb_delete('{"b":"qq", "a":null}','b');
select '{"b":"qq", "a":null}'::jsonb - 'b'

-- jsonb_delete_path - corresponds to #- operator
select jsonb_delete_path('{"a":1, "b": {"c": 5, "d":3}}'::jsonb, '{b,c}');
select '{"a":1, "b": {"c": 5, "d":3}}'::jsonb #- '{b,c}';

regards
Marcos

---

From: Michael Paquier <[email-masked]>
Date: Mon, 11 May 2026 11:08:36 +0900

> Just a comment on the correspondent operator ?

Well, it seems to me that the intention is that it is pointless to
document the functions because that the users need only to be aware of
the operators, and the operators are enough to manipulate the jsonb
blobs.  Documenting the functions would be just duplicating what we
already have for the operators, as listed here:
https://www.postgresql.org/docs/devel/functions-json.html
--
Michael

---

From: Marcos Pegoraro <[email-masked]>
Date: Mon, 11 May 2026 12:07:33 -0300

> https://www.postgresql.org/docs/devel/functions-json.html

A function is self explanatory, an operator is not.

If we do something like what was done in [1], we don't change much on the
page but at the same time we give the user both options.

regards
Marcos

[1] -
https://www.postgresql.org/docs/18/functions-string.html#FUNCTIONS-STRING-OTHER

---

From: Tom Lane <[email-masked]>
Date: Mon, 11 May 2026 11:19:44 -0400

> A function is self explanatory, an operator is not.

We have a general policy of not documenting functions that underlie
operators, simply because doing otherwise would bloat the
documentation enormously while not adding much value.  Do we really
need documentation entries for int4pl, int48gt, float84mul,
etc etc etc?

I'm sure there are a few places where that policy wasn't followed
for some reason, but I'm loath to abandon it.  There are circa
800 entries in pg_operator (and that's just for the core code).

			regards, tom lane

---

From: Marcos Pegoraro <[email-masked]>
Date: Mon, 11 May 2026 15:33:08 -0300

Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <[email-masked]> escreveu:

> There are circa 800 entries in pg_operator (and that's just for the core
> code).
>

It is precisely because of this number of operators that I would like to
document the functions related to them.
When you read SQL and there is an operator, you need to think, "Did I use
the right operator? I'll check the documentation to see if that's the one."
If I use a word, I have no doubt. The word Diff is completely different
than the word Equal, but the operator != is very similar to the operator =

Maybe we can find a way to have both on DOCs.
Maybe put function name just after operator definition
jsonb @> jsonb → boolean (jsonb_contains())
Maybe a tooltip on that operator.

I don't know how, but from a user's point of view, I know that not
documenting isn't the best approach.

regards
Marcos

---

From: Marcos Pegoraro <[email-masked]>
Date: Tue, 12 May 2026 18:45:05 -0300

Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <[email-masked]> escreveu:

> documentation enormously while not adding much value.
>

And if we have a separate page containing all non documented functions
related to their correspondent operators ?
Just one page with one table with all undocumented jsonb functions, another
table with undocumented interval functions and so on.

This way we document them and all main pages are not bloated with
duplicated functions.
We need only a "Click here to see the functions corresponding to the
operators you see in this table.", or something

What do you think ?

regards
Marcos