Horton

Thread

  1. Missing jsonb_ ... functions on DOCs

    Marcos Pegoraro <marcos@f10.com.br> — 2026-05-10T16:49:51Z

    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

  2. Re: Missing jsonb_ ... functions on DOCs

    Michael Paquier <michael@paquier.xyz> — 2026-05-11T02:08:36Z

    On Sun, May 10, 2026 at 01:49:51PM -0300, Marcos Pegoraro wrote:
> 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 ?

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

  3. Re: Missing jsonb_ ... functions on DOCs

    Marcos Pegoraro <marcos@f10.com.br> — 2026-05-11T15:07:33Z

    Em dom., 10 de mai. de 2026 às 23:08, Michael Paquier <michael@paquier.xyz>
escreveu:

> 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


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

  4. Re: Missing jsonb_ ... functions on DOCs

    Tom Lane <tgl@sss.pgh.pa.us> — 2026-05-11T15:19:44Z

    Marcos Pegoraro <marcos@f10.com.br> writes:
> Em dom., 10 de mai. de 2026 às 23:08, Michael Paquier <michael@paquier.xyz>
> escreveu:
>> 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

> 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

  5. Re: Missing jsonb_ ... functions on DOCs

    Marcos Pegoraro <marcos@f10.com.br> — 2026-05-11T18:33:08Z

    Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <tgl@sss.pgh.pa.us> 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

  6. Re: Missing jsonb_ ... functions on DOCs

    Marcos Pegoraro <marcos@f10.com.br> — 2026-05-12T21:45:05Z

    Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <tgl@sss.pgh.pa.us> escreveu:

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

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