Doc: add a bit to indices.sgml about what is an indexable clause.

We didn't explain this clearly until somewhere deep in the
"Extending SQL" chapter, but really it ought to be mentioned
in the introductory material too.

Discussion: https://postgr.es/m/4097442.1694967650@sss.pgh.pa.us

diff --git a/doc/src/sgml/indices.sgml b/doc/src/sgml/indices.sgml
index 55122129d586b8ce34fdc2a23da0f47b2e863aad..a9bb0bfab5cc5513c516c634fb821669e3259259 100644 (file)
--- a/doc/src/sgml/indices.sgml
+++ b/doc/src/sgml/indices.sgml
@@ -90,6 +90,39 @@ CREATE INDEX test1_id_index ON test1 (id);
    also significantly speed up queries with joins.
   
 
+  
+   In general, PostgreSQL indexes can be used
+   to optimize queries that contain one or more WHERE
+   or JOIN clauses of the form
+
+
+indexed-column indexable-operator comparison-value
+
+
+   Here, the indexed-column is whatever
+   column or expression the index has been defined on.
+   The indexable-operator is an operator that
+   is a member of the index's operator class for
+   the indexed column.  (More details about that appear below.)
+   And the comparison-value can be any
+   expression that is not volatile and does not reference the index's
+   table.
+  
+
+  
+   In some cases the query planner can extract an indexable clause of
+   this form from another SQL construct.  A simple example is that if
+   the original clause was
+
+
+comparison-value operator indexed-column
+
+
+   then it can be flipped around into indexable form if the
+   original operator has a commutator
+   operator that is a member of the index's operator class.
+  
+
   
    Creating an index on a large table can take a long time.  By default,
    PostgreSQL allows reads (SELECT statements) to occur
@@ -120,7 +153,7 @@ CREATE INDEX test1_id_index ON test1 (id);
    B-tree, Hash, GiST, SP-GiST, GIN, BRIN, and the extension 
    linkend="bloom">bloom.
    Each index type uses a different
-   algorithm that is best suited to different types of queries.
+   algorithm that is best suited to different types of indexable clauses.
    By default, the CREATE
    INDEX command creates
    B-tree indexes, which fit the most common situations.