From 2fbd80dafe72b27fd604952328814dcce297704c Mon Sep 17 00:00:00 2001
From: Mikhail Dobrinin <mvdobrinin@gmail.com>
Date: Tue, 25 Jan 2022 16:10:53 -0600
Subject: [PATCH] Add documentation for several jsonb functions.

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.
---
 doc/src/sgml/func.sgml | 65 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 0ee6974f1c..fdcb9abb6d 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -16593,6 +16593,71 @@ table2-mapping
         <returnvalue>t</returnvalue>
        </para></entry>
       </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>jsonb_exists</primary>
+        </indexterm>
+        <function>jsonb_exists</function> ( <type>jsonb</type> )
+        <returnvalue>boolean</returnvalue>
+       </para>
+       <para>
+        Checks if the text string exists as a top-level key or array element within the JSON value.
+        (This is functionally equivalent to the jsonb <literal>?</literal>
+        operator, but may be useful to call as a function in some cases, like when working with JDBC protocol.)
+       </para>
+       <para>
+        <literal>jsonb_exists('{"a":1, "b":2}'::jsonb, 'b')</literal>
+        <returnvalue>t</returnvalue>
+       </para>
+       <para>
+        <literal>jsonb_exists('["a","b"]'::jsonb, 'b')</literal>
+        <returnvalue>t</returnvalue>
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>jsonb_exists_any</primary>
+        </indexterm>
+        <function>jsonb_exists_any</function> ( <type>jsonb</type> )
+        <returnvalue>boolean</returnvalue>
+       </para>
+       <para>
+        Checks if any of the strings in the text array exist as top-level keys or array elements within the 
+        JSON value. (This is functionally equivalent to the jsonb <literal>?|</literal>
+        operator, but may be useful to call as a function in some cases, like when working with JDBC protocol.)
+       </para>
+       <para>
+        <literal>jsonb_exists_any('{"a":1, "b":2, "c":3}'::jsonb, array['b', 'd'])</literal>
+        <returnvalue>t</returnvalue>
+       </para></entry>
+      </row>
+
+      <row>
+       <entry role="func_table_entry"><para role="func_signature">
+        <indexterm>
+         <primary>jsonb_exists_all</primary>
+        </indexterm>
+        <function>jsonb_exists_all</function> ( <type>jsonb</type> )
+        <returnvalue>boolean</returnvalue>
+       </para>
+       <para>
+        Checks if all of the strings in the text array exist as top-level keys or array elements within the 
+        JSON value. (This is functionally equivalent to the jsonb <literal>?&amp;</literal>
+        operator, but may be useful to call as a function in some cases, like when working with JDBC protocol.)
+       </para>
+       <para>
+        <literal>jsonb_exists_all('{"a":1, "b":2, "c":3}'::jsonb, array['b', 'd'])</literal>
+        <returnvalue>f</returnvalue>
+       </para>
+       <para>
+        <literal>jsonb_exists_all('{"a":1, "b":2, "c":3}'::jsonb, array['b', 'c'])</literal>
+        <returnvalue>t</returnvalue>
+       </para></entry>
+      </row>
      </tbody>
     </tgroup>
    </table>
-- 
2.20.1