Writeup from Tom Lane on how costs are estimated.

diff --git a/doc/src/sgml/indexcost.sgml b/doc/src/sgml/indexcost.sgml
new file mode 100644 (file)
index 0000000..4f9702c
--- /dev/null
+++ b/doc/src/sgml/indexcost.sgml
@@ -0,0 +1,236 @@
+ 
+  Index Cost Estimation Functions
+
+  
+   Author
+
+   
+    Written by Tom Lane
+    on 2000-01-24.
+   
+  
+
+
+
+  
+   Every index access method must provide a cost estimation function for
+   use by the planner/optimizer.  The procedure OID of this function is
+   given in the amcostestimate field of the access
+   method's pg_am entry.
+
+   
+    
+     Prior to Postgres 7.0, a different scheme was used for registering
+     index-specific cost estimation functions.
+    
+   
+  
+
+  
+   The amcostestimate function is given a list of WHERE clauses that have
+   been determined to be usable with the index.  It must return estimates
+   of the cost of accessing the index and the selectivity of the WHERE
+   clauses (that is, the fraction of main-table tuples that will be
+   retrieved during the index scan).  For simple cases, nearly all the
+   work of the cost estimator can be done by calling standard routines
+   in the optimizer; the point of having an amcostestimate function is
+   to allow index access methods to provide index-type-specific knowledge,
+   in case it is possible to improve on the standard estimates.
+  
+
+  
+   Each amcostestimate function must have the signature:
+
+   
+void
+amcostestimate (Query *root,
+                RelOptInfo *rel,
+                IndexOptInfo *index,
+                List *indexQuals,
+                Cost *indexAccessCost,
+                Selectivity *indexSelectivity);
+   
+
+   The first four parameters are inputs:
+
+   
+    
+     root
+     
+      
+       The query being processed.
+      
+     
+    
+
+    
+     rel
+     
+      
+       The relation the index is on.
+      
+     
+    
+
+    
+     index
+     
+      
+       The index itself.
+      
+     
+    
+
+    
+     indexQuals
+     
+      
+       List of index qual clauses (implicitly ANDed);
+       a NIL list indicates no qualifiers are available.
+      
+     
+    
+   
+  
+
+  
+   The last two parameters are pass-by-reference outputs:
+
+   
+    
+     *indexAccessCost
+     
+      
+       Set to cost of index processing.
+      
+     
+    
+
+    
+     *indexSelectivity
+     
+      
+       Set to index selectivity
+      
+     
+    
+   
+  
+
+  
+   Note that cost estimate functions must be written in C, not in SQL or
+   any available procedural language, because they must access internal
+   data structures of the planner/optimizer.
+  
+
+  
+   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 main-table tuples that are identified by the index.
+  
+
+  
+   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
+   of a lossy index, this will typically be higher than the fraction of
+   tuples that actually pass the given qual conditions.
+  
+
+  
+   Cost Estimation
+   
+    A typical cost estimator will proceed as follows:
+   
+
+   
+    
+     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():
+
+     
+*indexSelectivity = clauselist_selec(root, indexQuals);
+     
+    
+   
+
+   
+    
+     Estimate the number of index tuples that will be visited during the
+     scan.  For many index types this is the same as indexSelectivity times
+     the number of tuples in the index, but it might be more.  (Note that the
+     index's size in pages and tuples is available from the IndexOptInfo struct.)
+    
+   
+
+   
+    
+     Estimate the number of index pages that will be retrieved during the scan.
+     This might be just indexSelectivity times the index's size in pages.
+    
+   
+
+   
+    
+     Compute the index access cost as
+
+     
+*indexAccessCost = numIndexPages + cpu_index_page_weight * numIndexTuples;
+     
+    
+   
+  
+
+  
+   Examples of cost estimator functions can be found in
+   src/backend/utils/adt/selfuncs.c.
+  
+
+  
+   By convention, the pg_proc entry for an
+   amcostestimate function should show
+
+   
+prorettype = 0
+pronargs = 6
+proargtypes = 0 0 0 0 0 0
+   
+
+   We use zero ("opaque") for all the arguments since none of them have types
+   that are known in pg_type.
+  
+ 
+
+