11<!--
2- $Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.2 2000/03/3103:27:40 thomas Exp $
2+ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.3 2000/03/3117:18:26 tgl Exp $
33-->
44
55 <chapter>
@@ -14,20 +14,12 @@ $Header: /cvsroot/pgsql/doc/src/sgml/Attic/indexcost.sgml,v 2.2 2000/03/31 03:27
1414 </para>
1515 </note>
1616
17- <!--
18- I have written the attached bit of doco about the new index cost
19- estimator procedure definition, but I am not sure where to put it.
20- There isn't (AFAICT) any existing documentation about how to make
21- a new kind of index, which would be the proper place for it.
22- May I impose on you to find/make a place for this and mark it up
23- properly?
24-
25- Also, doc/src/graphics/catalogs.ag needs to be updated, but I have
26- no idea how. (The amopselect and amopnpages fields of pg_amop
27- are gone; pg_am has a new field amcostestimate.)
28-
29- regards, tom lane
30- -->
17+ <note>
18+ <para>
19+ This must eventually become part of a much larger chapter about
20+ writing new index access methods.
21+ </para>
22+ </note>
3123
3224 <para>
3325 Every index access method must provide a cost estimation function for
@@ -64,7 +56,8 @@ amcostestimate (Query *root,
6456 RelOptInfo *rel,
6557 IndexOptInfo *index,
6658 List *indexQuals,
67- Cost *indexAccessCost,
59+ Cost *indexStartupCost,
60+ Cost *indexTotalCost,
6861 Selectivity *indexSelectivity);
6962 </programlisting>
7063
@@ -111,14 +104,23 @@ amcostestimate (Query *root,
111104 </para>
112105
113106 <para>
114- The lasttwo parameters are pass-by-reference outputs:
107+ The lastthree parameters are pass-by-reference outputs:
115108
116109 <variablelist>
117110 <varlistentry>
118- <term>*indexAccessCost </term>
111+ <term>*indexStartupCost </term>
119112 <listitem>
120113 <para>
121- Set to cost of index processing.
114+ Set to cost of index startup processing
115+ </para>
116+ </listitem>
117+ </varlistentry>
118+
119+ <varlistentry>
120+ <term>*indexTotalCost</term>
121+ <listitem>
122+ <para>
123+ Set to total cost of index processing
122124 </para>
123125 </listitem>
124126 </varlistentry>
@@ -141,15 +143,29 @@ amcostestimate (Query *root,
141143 </para>
142144
143145 <para>
144- The indexAccessCost should be computed in the units used by
145- src/backend/optimizer/path/costsize.c: a disk block fetch has cost 1.0,
146- and the cost of processing one index tuple should usually be taken as
147- cpu_index_page_weight (which is a user-adjustable optimizer parameter).
148- The access cost should include all disk and CPU costs associated with
149- scanning the index itself, but NOT the cost of retrieving or processing
146+ The index access costs should be computed in the units used by
147+ src/backend/optimizer/path/costsize.c: a sequential disk block fetch
148+ has cost 1.0, a nonsequential fetch has cost random_page_cost, and
149+ the cost of processing one index tuple should usually be taken as
150+ cpu_index_tuple_cost (which is a user-adjustable optimizer parameter).
151+ In addition, an appropriate multiple of cpu_operator_cost should be charged
152+ for any comparison operators invoked during index processing (especially
153+ evaluation of the indexQuals themselves).
154+ </para>
155+
156+ <para>
157+ The access costs should include all disk and CPU costs associated with
158+ scanning the index itself, but NOT the costs of retrieving or processing
150159 the main-table tuples that are identified by the index.
151160 </para>
152161
162+ <para>
163+ The "startup cost" is the part of the total scan cost that must be expended
164+ before we can begin to fetch the first tuple. For most indexes this can
165+ be taken as zero, but an index type with a high startup cost might want
166+ to set it nonzero.
167+ </para>
168+
153169 <para>
154170 The indexSelectivity should be set to the estimated fraction of the main
155171 table tuples that will be retrieved during the index scan. In the case
@@ -167,10 +183,11 @@ amcostestimate (Query *root,
167183 <para>
168184 Estimate and return the fraction of main-table tuples that will be visited
169185 based on the given qual conditions. In the absence of any index-type-specific
170- knowledge, use the standard optimizer functionclauselist_selec ():
186+ knowledge, use the standard optimizer functionclauselist_selectivity ():
171187
172188 <programlisting>
173- *indexSelectivity = clauselist_selec(root, indexQuals);
189+ *indexSelectivity = clauselist_selectivity(root, indexQuals,
190+ lfirsti(rel->relids));
174191 </programlisting>
175192 </para>
176193 </step>
@@ -193,10 +210,18 @@ amcostestimate (Query *root,
193210
194211 <step>
195212 <para>
196- Compute the index access cost as
213+ Compute the index access cost. A generic estimator might do this:
197214
198215 <programlisting>
199- *indexAccessCost = numIndexPages + cpu_index_page_weight * numIndexTuples;
216+ /*
217+ * Our generic assumption is that the index pages will be read
218+ * sequentially, so they have cost 1.0 each, not random_page_cost.
219+ * Also, we charge for evaluation of the indexquals at each index tuple.
220+ * All the costs are assumed to be paid incrementally during the scan.
221+ */
222+ *indexStartupCost = 0;
223+ *indexTotalCost = numIndexPages +
224+ (cpu_index_tuple_cost + cost_qual_eval(indexQuals)) * numIndexTuples;
200225 </programlisting>
201226 </para>
202227 </step>
@@ -213,8 +238,8 @@ amcostestimate (Query *root,
213238
214239 <programlisting>
215240prorettype = 0
216- pronargs =6
217- proargtypes = 0 0 0 0 0 0
241+ pronargs =7
242+ proargtypes = 0 0 0 0 0 0 0
218243 </programlisting>
219244
220245 We use zero ("opaque") for all the arguments since none of them have types