Update index cost estimation docs to final 7.0 scheme.

diff --git a/doc/src/sgml/indexcost.sgml b/doc/src/sgml/indexcost.sgml
index 175e0576f02e3bbad4d0c6df16bf6963e4338c71..8153c41a9b342853a4904e61c09432a24aaefc8a 100644 (file)
--- a/doc/src/sgml/indexcost.sgml
+++ b/doc/src/sgml/indexcost.sgml
@@ -1,5 +1,5 @@
 
 
  
@@ -14,20 +14,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.2 2000/03/31 03:27
    
   
 
-
+   
+    
+     This must eventually become part of a much larger chapter about
+     writing new index access methods.
+    
+   
 
   
    Every index access method must provide a cost estimation function for
@@ -64,7 +56,8 @@ amcostestimate (Query *root,
                 RelOptInfo *rel,
                 IndexOptInfo *index,
                 List *indexQuals,
-                Cost *indexAccessCost,
+                Cost *indexStartupCost,
+                Cost *indexTotalCost,
                 Selectivity *indexSelectivity);
    
 
@@ -111,14 +104,23 @@ amcostestimate (Query *root,
   
 
   
-   The last two parameters are pass-by-reference outputs:
+   The last three parameters are pass-by-reference outputs:
 
    
     
-     *indexAccessCost
+     *indexStartupCost
      
       
-       Set to cost of index processing.
+       Set to cost of index startup processing
+      
+     
+    
+
+    
+     *indexTotalCost
+     
+      
+       Set to total cost of index processing
       
      
     
@@ -141,15 +143,29 @@ amcostestimate (Query *root,
   
 
   
-   The indexAccessCost should be computed in the units used by
-   src/backend/optimizer/path/costsize.c: a disk block fetch has cost 1.0,
-   and the cost of processing one index tuple should usually be taken as
-   cpu_index_page_weight (which is a user-adjustable optimizer parameter).
-   The access cost should include all disk and CPU costs associated with
-   scanning the index itself, but NOT the cost of retrieving or processing
+   The index access costs should be computed in the units used by
+   src/backend/optimizer/path/costsize.c: a sequential disk block fetch
+   has cost 1.0, a nonsequential fetch has cost random_page_cost, and
+   the cost of processing one index tuple should usually be taken as
+   cpu_index_tuple_cost (which is a user-adjustable optimizer parameter).
+   In addition, an appropriate multiple of cpu_operator_cost should be charged
+   for any comparison operators invoked during index processing (especially
+   evaluation of the indexQuals themselves).
+  
+
+  
+   The access costs should include all disk and CPU costs associated with
+   scanning the index itself, but NOT the costs of retrieving or processing
    the main-table tuples that are identified by the index.
   
 
+  
+   The "startup cost" is the part of the total scan cost that must be expended
+   before we can begin to fetch the first tuple.  For most indexes this can
+   be taken as zero, but an index type with a high startup cost might want
+   to set it nonzero.
+  
+
   
    The indexSelectivity should be set to the estimated fraction of the main
    table tuples that will be retrieved during the index scan.  In the case
@@ -167,10 +183,11 @@ amcostestimate (Query *root,
     
      Estimate and return the fraction of main-table tuples that will be visited
      based on the given qual conditions.  In the absence of any index-type-specific
-     knowledge, use the standard optimizer function clauselist_selec():
+     knowledge, use the standard optimizer function clauselist_selectivity():
 
      
-*indexSelectivity = clauselist_selec(root, indexQuals);
+*indexSelectivity = clauselist_selectivity(root, indexQuals,
+                                           lfirsti(rel->relids));
      
     
    
@@ -193,10 +210,18 @@ amcostestimate (Query *root,
 
    
     
-     Compute the index access cost as
+     Compute the index access cost.  A generic estimator might do this:
 
      
-*indexAccessCost = numIndexPages + cpu_index_page_weight * numIndexTuples;
+    /*
+     * Our generic assumption is that the index pages will be read
+     * sequentially, so they have cost 1.0 each, not random_page_cost.
+     * Also, we charge for evaluation of the indexquals at each index tuple.
+     * All the costs are assumed to be paid incrementally during the scan.
+     */
+    *indexStartupCost = 0;
+    *indexTotalCost = numIndexPages +
+        (cpu_index_tuple_cost + cost_qual_eval(indexQuals)) * numIndexTuples;
      
     
    
@@ -213,8 +238,8 @@ amcostestimate (Query *root,
 
    
 prorettype = 0
-pronargs = 6
-proargtypes = 0 0 0 0 0 0
+pronargs = 7
+proargtypes = 0 0 0 0 0 0 0
    
 
    We use zero ("opaque") for all the arguments since none of them have types