summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Lane2015-10-29 22:54:35 +0000
committerTom Lane2015-10-29 22:55:02 +0000
commit23937a4253490bf0c06aef0b8658270176f52de4 (patch)
treea4d41e47dd2cbc7e8420e36321e47aa463b39464
parentc5130e8ee09e5ae605f3aa944a31dd9021c1d3dd (diff)
Docs: add example clarifying use of nested JSON containment.
Show how this can be used in practice to make queries simpler and more flexible. Also, draw an explicit contrast to the existence operator, which doesn't work that way. Peter Geoghegan and Tom Lane
-rw-r--r--doc/src/sgml/json.sgml28
1 files changed, 28 insertions, 0 deletions
diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index 118fb35e25..3cf78d6394 100644
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -349,6 +349,34 @@ SELECT '"foo"'::jsonb ? 'foo';
need to be searched linearly.
</para>
+ <tip>
+ <para>
+ Because JSON containment is nested, an appropriate query can skip
+ explicit selection of sub-objects. As an example, suppose that we have
+ a <structfield>doc</> column containing objects at the top level, with
+ most objects containing <literal>tags</> fields that contain arrays of
+ sub-objects. This query finds entries in which sub-objects containing
+ both <literal>"term":"paris"</> and <literal>"term":"food"</> appear,
+ while ignoring any such keys outside the <literal>tags</> array:
+<programlisting>
+SELECT doc-&gt;'site_name' FROM websites
+ WHERE doc @&gt; '{"tags":[{"term":"paris"}, {"term":"food"}]}';
+</programlisting>
+ One could accomplish the same thing with, say,
+<programlisting>
+SELECT doc-&gt;'site_name' FROM websites
+ WHERE doc-&gt;'tags' @&gt; '[{"term":"paris"}, {"term":"food"}]';
+</programlisting>
+ but that approach is less flexible, and often less efficient as well.
+ </para>
+
+ <para>
+ On the other hand, the JSON existence operator is not nested: it will
+ only look for the specified key or array element at top level of the
+ JSON value.
+ </para>
+ </tip>
+
<para>
The various containment and existence operators, along with all other
JSON operators and functions are documented