Doc: copy-edit "jsonb Indexing" section.

The patch introducing jsonpath dropped a para about that between
two related examples, and didn't bother updating the introductory
sentences that it falsified.  The grammar was pretty shaky as well.

diff --git a/doc/src/sgml/json.sgml b/doc/src/sgml/json.sgml
index 0ffb5a708d937c435e2852c88a05c9db698f2e9e..78125bc8597b9d98dd5f46d7f39cb78247889484 100644 (file)
--- a/doc/src/sgml/json.sgml
+++ b/doc/src/sgml/json.sgml
@@ -415,9 +415,10 @@ SELECT doc->'site_name' FROM websites
   
   
     The default GIN operator class for jsonb supports queries with
-    top-level key-exists operators ?, ?&
-    and ?| operators and path/value-exists operator
-    @>.
+    the key-exists operators ?, ?|
+    and ?&, the containment operator
+    @>, and the jsonpath match
+    operators @? and @@.
     (For details of the semantics that these operators
     implement, see .)
     An example of creating an index with this operator class is:
@@ -425,7 +426,8 @@ SELECT doc->'site_name' FROM websites
 CREATE INDEX idxgin ON api USING GIN (jdoc);
 
     The non-default GIN operator class jsonb_path_ops
-    supports indexing the @> operator only.
+    does not support the key-exists operators, but it does support
+    @>, @? and @@.
     An example of creating an index with this operator class is:
 
 CREATE INDEX idxginp ON api USING GIN (jdoc jsonb_path_ops);
@@ -482,22 +484,7 @@ CREATE INDEX idxgintags ON api USING GIN ((jdoc -> 'tags'));
     (More information on expression indexes can be found in 
     linkend="indexes-expressional"/>.)
   
-  
-    Also, GIN index supports @@ and @?
-    operators, which perform jsonpath matching.
-
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
-
-
-SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")';
-
-    GIN index extracts statements of following form out of
-    jsonpath: accessors_chain = const.
-    Accessors chain may consist of .key,
-    [*], and [index] accessors.
-    jsonb_ops additionally supports .*
-    and .** accessors.
-  
+
   
     Another approach to querying is to exploit containment, for example:
 
@@ -514,10 +501,33 @@ SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @> '{"tags": ["qu
     index.
   
 
+  
+    GIN indexes also support the @?
+    and @@ operators, which
+    perform jsonpath matching.  Examples are
+
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @? '$.tags[*] ? (@ == "qui")';
+
+
+SELECT jdoc->'guid', jdoc->'name' FROM api WHERE jdoc @@ '$.tags[*] == "qui"';
+
+    For these operators, a GIN index extracts clauses of the form
+    accessors_chain
+    = constant out of
+    the jsonpath pattern, and does the index search based on
+    the keys and values mentioned in these clauses.  The accessors chain
+    may include .key,
+    [*],
+    and [index] accessors.
+    The jsonb_ops operator class also
+    supports .* and .** accessors,
+    but the jsonb_path_ops operator class does not.
+  
+
   
     Although the jsonb_path_ops operator class supports
-    only queries with the @>, @@
-    and @? operators, it has notable
+    only queries with the @>, @?
+    and @@ operators, it has notable
     performance advantages over the default operator
     class jsonb_ops.  A jsonb_path_ops
     index is usually much smaller than a jsonb_ops