public inbox for [email protected]
help / color / mirror / Atom feedMissing jsonb_ ... functions on DOCs
6+ messages / 3 participants
[nested] [flat]
* Missing jsonb_ ... functions on DOCs
@ 2026-05-10 16:49 Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Re: Missing jsonb_ ... functions on DOCs Michael Paquier <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Marcos Pegoraro @ 2026-05-10 16:49 UTC (permalink / raw)
To: pgsql-hackers
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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Missing jsonb_ ... functions on DOCs
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
@ 2026-05-11 02:08 ` Michael Paquier <[email protected]>
2026-05-11 15:07 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Michael Paquier @ 2026-05-11 02:08 UTC (permalink / raw)
To: Marcos Pegoraro <[email protected]>; +Cc: pgsql-hackers
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
Attachments:
[application/pgp-signature] signature.asc (833B, 2-signature.asc)
download
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Missing jsonb_ ... functions on DOCs
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Re: Missing jsonb_ ... functions on DOCs Michael Paquier <[email protected]>
@ 2026-05-11 15:07 ` Marcos Pegoraro <[email protected]>
2026-05-11 15:19 ` Re: Missing jsonb_ ... functions on DOCs Tom Lane <[email protected]>
0 siblings, 1 reply; 6+ messages in thread
From: Marcos Pegoraro @ 2026-05-11 15:07 UTC (permalink / raw)
To: Michael Paquier <[email protected]>; +Cc: pgsql-hackers
Em dom., 10 de mai. de 2026 às 23:08, Michael Paquier <[email protected]>
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
Attachments:
[application/octet-stream] DOC jsonb functions with their related operators.diff (3.5K, 3-DOC%20jsonb%20functions%20with%20their%20related%20operators.diff)
download | inline diff:
From 3b6fd9ffbdd3d301c5e36ee79ac712ce491674e7 Mon Sep 17 00:00:00 2001
From: PegoraroF10 <[email protected]>
Date: Mon, 11 May 2026 11:58:28 -0300
Subject: [PATCH] Added to DOC jsonb functions to their equivalent operators
---
doc/src/sgml/func/func-json.sgml | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)
diff --git a/doc/src/sgml/func/func-json.sgml b/doc/src/sgml/func/func-json.sgml
index 3d97e2b5375..ffe81b70a2c 100644
--- a/doc/src/sgml/func/func-json.sgml
+++ b/doc/src/sgml/func/func-json.sgml
@@ -275,6 +275,9 @@
Does the first JSON value contain the second?
(See <xref linkend="json-containment"/> for details about containment.)
</para>
+ <para>
+ Equivalent to the <function>jsonb_contains()</function> function.
+ </para>
<para>
<literal>'{"a":1, "b":2}'::jsonb @> '{"b":2}'::jsonb</literal>
<returnvalue>t</returnvalue>
@@ -289,6 +292,9 @@
<para>
Is the first JSON value contained in the second?
</para>
+ <para>
+ Equivalent to the <function>jsonb_contained()</function> function.
+ </para>
<para>
<literal>'{"b":2}'::jsonb <@ '{"a":1, "b":2}'::jsonb</literal>
<returnvalue>t</returnvalue>
@@ -304,6 +310,9 @@
Does the text string exist as a top-level key or array element within
the JSON value?
</para>
+ <para>
+ Equivalent to the <function>jsonb_exists()</function> function.
+ </para>
<para>
<literal>'{"a":1, "b":2}'::jsonb ? 'b'</literal>
<returnvalue>t</returnvalue>
@@ -323,6 +332,9 @@
Do any of the strings in the text array exist as top-level keys or
array elements?
</para>
+ <para>
+ Equivalent to the <function>jsonb_exists_any()</function> function.
+ </para>
<para>
<literal>'{"a":1, "b":2, "c":3}'::jsonb ?| array['b', 'd']</literal>
<returnvalue>t</returnvalue>
@@ -338,6 +350,9 @@
Do all of the strings in the text array exist as top-level keys or
array elements?
</para>
+ <para>
+ Equivalent to the <function>jsonb_exists_all()</function> function.
+ </para>
<para>
<literal>'["a", "b", "c"]'::jsonb ?& array['a', 'b']</literal>
<returnvalue>t</returnvalue>
@@ -360,6 +375,9 @@
Does not operate recursively: only the top-level array or object
structure is merged.
</para>
+ <para>
+ Equivalent to the <function>jsonb_concat()</function> function.
+ </para>
<para>
<literal>'["a", "b"]'::jsonb || '["a", "d"]'::jsonb</literal>
<returnvalue>["a", "b", "a", "d"]</returnvalue>
@@ -395,6 +413,9 @@
Deletes a key (and its value) from a JSON object, or matching string
value(s) from a JSON array.
</para>
+ <para>
+ Equivalent to the <function>jsonb_delete()</function> function.
+ </para>
<para>
<literal>'{"a": "b", "c": "d"}'::jsonb - 'a'</literal>
<returnvalue>{"c": "d"}</returnvalue>
@@ -444,6 +465,9 @@
Deletes the field or array element at the specified path, where path
elements can be either field keys or array indexes.
</para>
+ <para>
+ Equivalent to the <function>jsonb_delete_path()</function> function.
+ </para>
<para>
<literal>'["a", {"b":1}]'::jsonb #- '{1,b}'</literal>
<returnvalue>["a", {}]</returnvalue>
--
2.51.2.windows.1
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Missing jsonb_ ... functions on DOCs
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Re: Missing jsonb_ ... functions on DOCs Michael Paquier <[email protected]>
2026-05-11 15:07 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
@ 2026-05-11 15:19 ` Tom Lane <[email protected]>
2026-05-11 18:33 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-12 21:45 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
0 siblings, 2 replies; 6+ messages in thread
From: Tom Lane @ 2026-05-11 15:19 UTC (permalink / raw)
To: Marcos Pegoraro <[email protected]>; +Cc: Michael Paquier <[email protected]>; pgsql-hackers
Marcos Pegoraro <[email protected]> writes:
> Em dom., 10 de mai. de 2026 às 23:08, Michael Paquier <[email protected]>
> 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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Missing jsonb_ ... functions on DOCs
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Re: Missing jsonb_ ... functions on DOCs Michael Paquier <[email protected]>
2026-05-11 15:07 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 15:19 ` Re: Missing jsonb_ ... functions on DOCs Tom Lane <[email protected]>
@ 2026-05-11 18:33 ` Marcos Pegoraro <[email protected]>
1 sibling, 0 replies; 6+ messages in thread
From: Marcos Pegoraro @ 2026-05-11 18:33 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Michael Paquier <[email protected]>; pgsql-hackers
Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <[email protected]> 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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Missing jsonb_ ... functions on DOCs
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Re: Missing jsonb_ ... functions on DOCs Michael Paquier <[email protected]>
2026-05-11 15:07 ` Re: Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 15:19 ` Re: Missing jsonb_ ... functions on DOCs Tom Lane <[email protected]>
@ 2026-05-12 21:45 ` Marcos Pegoraro <[email protected]>
1 sibling, 0 replies; 6+ messages in thread
From: Marcos Pegoraro @ 2026-05-12 21:45 UTC (permalink / raw)
To: Tom Lane <[email protected]>; +Cc: Michael Paquier <[email protected]>; pgsql-hackers
Em seg., 11 de mai. de 2026 às 12:19, Tom Lane <[email protected]> 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
^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2026-05-12 21:45 UTC | newest]
Thread overview: 6+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2026-05-10 16:49 Missing jsonb_ ... functions on DOCs Marcos Pegoraro <[email protected]>
2026-05-11 02:08 ` Michael Paquier <[email protected]>
2026-05-11 15:07 ` Marcos Pegoraro <[email protected]>
2026-05-11 15:19 ` Tom Lane <[email protected]>
2026-05-11 18:33 ` Marcos Pegoraro <[email protected]>
2026-05-12 21:45 ` Marcos Pegoraro <[email protected]>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox