public inbox for [email protected]
help / color / mirror / Atom feedFrom: Mikhail Dobrinin <[email protected]>
To: [email protected]
Subject: JSONB docs patch
Date: Tue, 25 Jan 2022 16:38:05 -0600
Message-ID: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com> (raw)
Hello,
I have come across some missing documentation that I think could benefit
the community.
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-qu...),
so it is useful for users of PG to know the function equivalents of these
operators.
I have attached the patch as an attachment to this email. The documentation
builds correctly without any lint errors after applying the patch locally.
This is my first time contributing, so let me know if there is anything
else I should do (add to commitfest etc).
Cheers!
Mikhail Dobrinin
Attachments:
[application/octet-stream] jsonb-docs-v1.diff (3.8K, ../CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@mail.gmail.com/3-jsonb-docs-v1.diff)
download | inline diff:
From 2fbd80dafe72b27fd604952328814dcce297704c Mon Sep 17 00:00:00 2001
From: Mikhail Dobrinin <[email protected]>
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>?&</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
view thread (3+ 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: JSONB docs patch
In-Reply-To: <CABKYkG77WX0JhAb7P_YQO2x1-+Vb_=fKxbrgTNbDLo89fjpvLg@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