Doc: minor improvements for section 11.2 "Index Types".

Break the per-index-type discussions into 's so as to make
them more visually separate and easier to find.  Improve the markup,
and make a couple of small wording adjustments.

This also fixes one stray reference to the now-deprecated point
operators <^ and >^.

Dagfinn Ilmari Mannsåker, reviewed by David Johnston and Jürgen Purtz

Discussion: https://postgr.es/m/[email protected]

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 671299ff059d972ff95bdb1d67ed4c89bf5040b2..623962d1d89bd89fc9dbbbb1159c70ddff5060b2 100644 (file)
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -118,32 +118,39 @@ CREATE INDEX test1_id_index ON test1 (id);
    B-tree, Hash, GiST, SP-GiST, GIN and BRIN.
    Each index type uses a different
    algorithm that is best suited to different types of queries.
-   By default, the CREATE INDEX command creates
+   By default, the CREATE
+   INDEX command creates
    B-tree indexes, which fit the most common situations.
+   The other index types are selected by writing the keyword
+   USING followed by the index type name.
+   For example, to create a Hash index:
+
+CREATE INDEX name ON table USING HASH (column);
+
   
 
-  
+  
+   B-Tree
+
    
     index
-    B-tree
+    B-Tree
    
    
-    B-tree
+    B-Tree
     index
    
+
+  
    B-trees can handle equality and range queries on data that can be sorted
    into some ordering.
    In particular, the PostgreSQL query planner
    will consider using a B-tree index whenever an indexed column is
    involved in a comparison using one of these operators:
 
-   
-    <
-    <=
-    =
-    >=
-    >
-   
+
+<   <=   =   >=   >
+
 
    Constructs equivalent to combinations of these operators, such as
    BETWEEN and IN, can also be implemented with
@@ -172,8 +179,11 @@ CREATE INDEX test1_id_index ON test1 (id);
    This is not always faster than a simple scan and sort, but it is
    often helpful.
   
+  
+
+  
+   Hash
 
-  
    
     index
     hash
@@ -182,17 +192,24 @@ CREATE INDEX test1_id_index ON test1 (id);
     hash
     index
    
-   Hash indexes can only handle simple equality comparisons.
+
+  
+   Hash indexes store a 32-bit hash code derived from the
+   value of the indexed column. Hence,
+   such indexes can only handle simple equality comparisons.
    The query planner will consider using a hash index whenever an
    indexed column is involved in a comparison using the
-   = operator.
-   The following command is used to create a hash index:
+   equal operator:
+
 
-CREATE INDEX name ON table USING HASH (column);
+=
 
   
+  
+
+  
+   GiST
 
-  
    
     index
     GiST
@@ -201,6 +218,8 @@ CREATE INDEX name ON table
     GiST
     index
    
+
+  
    GiST indexes are not a single kind of index, but rather an infrastructure
    within which many different indexing strategies can be implemented.
    Accordingly, the particular operators with which a GiST index can be
@@ -210,20 +229,9 @@ CREATE INDEX name ON table
    for several two-dimensional geometric data types, which support indexed
    queries using these operators:
 
-   
-    <<
-    &<
-    &>
-    >>
-    <<|
-    &<|
-    |&>
-    |>>
-    @>
-    <@
-    ~=
-    &&
-   
+
+<<   &<   &>   >>   <<|   &<|   |&>   |>>   @>   <@   ~=   &&
+
 
    (See  for the meaning of
    these operators.)
@@ -246,8 +254,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
    In , operators that can be
    used in this way are listed in the column Ordering Operators.
   
+  
+
+  
+   SP-GiST
 
-  
    
     index
     SP-GiST
@@ -256,6 +267,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
     SP-GiST
     index
    
+
+  
    SP-GiST indexes, like GiST indexes, offer an infrastructure that supports
    various kinds of searches.  SP-GiST permits implementation of a wide range
    of different non-balanced disk-based data structures, such as quadtrees,
@@ -264,14 +277,9 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
    for two-dimensional points, which support indexed
    queries using these operators:
 
-   
-    <<
-    >>
-    ~=
-    <@
-    <^
-    >^
-   
+
+<<   >>   ~=   <@   <<|   |>>
+
 
    (See  for the meaning of
    these operators.)
@@ -283,11 +291,14 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
   
    Like GiST, SP-GiST supports nearest-neighbor searches.
    For SP-GiST operator classes that support distance ordering, the
-   corresponding operator is specified in the Ordering Operators
+   corresponding operator is listed in the Ordering Operators
    column in .
   
+  
+
+  
+   GIN
 
-  
    
     index
     GIN
@@ -296,6 +307,8 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
     GIN
     index
    
+
+  
    GIN indexes are inverted indexes which are appropriate for
    data values that contain multiple component values, such as arrays.  An
    inverted index contains a separate entry for each component value, and
@@ -312,12 +325,9 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
    PostgreSQL includes a GIN operator class
    for arrays, which supports indexed queries using these operators:
 
-   
-    <@
-    @>
-    =
-    &&
-   
+
+<@   @>   =   &&
+
 
    (See  for the meaning of
    these operators.)
@@ -327,8 +337,11 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
    classes are available in the contrib collection or as separate
    projects.  For more information see .
   
+  
+
+  
+   BRIN
 
-  
    
     index
     BRIN
@@ -337,8 +350,12 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
     BRIN
     index
    
+
+  
    BRIN indexes (a shorthand for Block Range INdexes) store summaries about
    the values stored in consecutive physical block ranges of a table.
+   Thus, they are most effective for columns whose values are well-correlated
+   with the physical order of the table rows.
    Like GiST, SP-GiST and GIN,
    BRIN can support many different indexing strategies,
    and the particular operators with which a BRIN index can be used
@@ -348,18 +365,15 @@ SELECT * FROM places ORDER BY location <-> point '(101,456)' LIMIT 10;
    values in the column for each block range.  This supports indexed queries
    using these operators:
 
-   
-    <
-    <=
-    =
-    >=
-    >
-   
+
+<   <=   =   >=   >
+
 
    The BRIN operator classes included in the standard distribution are
    documented in .
    For more information see .
   
+