public inbox for [email protected]  

help / color / mirror / Atom feed

From: Marcos Pegoraro <[email protected]>
To: Michael Paquier <[email protected]>
Cc: pgsql-hackers <[email protected]>
Subject: Re: Missing jsonb_ ... functions on DOCs
Date: Mon, 11 May 2026 12:07:33 -0300
Message-ID: <CAB-JLwb+m=gspBheMGWq9TCPqgD70K30AQ3bNxPzg3KBsym2Bg@mail.gmail.com> (raw)
In-Reply-To: <[email protected]>
References: <CAB-JLwbPuNY+4Ez48TZpXg-ZuxRSJ_igsNOa-nX7jBEs97qHCQ@mail.gmail.com>
	<[email protected]>

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 &#64;&gt; '{"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 &lt;@ '{"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 ?&amp; 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

view thread (6+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected]
  Subject: Re: Missing jsonb_ ... functions on DOCs
  In-Reply-To: <CAB-JLwb+m=gspBheMGWq9TCPqgD70K30AQ3bNxPzg3KBsym2Bg@mail.gmail.com>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox