From e2fa76d80ba571d4de8992de6386536867250474 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Fri, 27 Jan 2012 19:26:38 -0500
Subject: Use parameterized paths to generate inner indexscans more flexibly.

This patch fixes the planner so that it can generate nestloop-with-
inner-indexscan plans even with one or more levels of joining between
the indexscan and the nestloop join that is supplying the parameter.
The executor was fixed to handle such cases some time ago, but the
planner was not ready.  This should improve our plans in many situations
where join ordering restrictions formerly forced complete table scans.

There is probably a fair amount of tuning work yet to be done, because
of various heuristics that have been added to limit the number of
parameterized paths considered.  However, we are not going to find out
what needs to be adjusted until the code gets some real-world use, so
it's time to get it in there where it can be tested easily.

Note API change for index AM amcostestimate functions.  I'm not aware of
any non-core index AMs, but if there are any, they will need minor
adjustments.
---
 doc/src/sgml/indexam.sgml | 25 ++++++++++++-------------
 1 file changed, 12 insertions(+), 13 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/indexam.sgml b/doc/src/sgml/indexam.sgml
index 07c816c38f2..28f2ae16275 100644
--- a/doc/src/sgml/indexam.sgml
+++ b/doc/src/sgml/indexam.sgml
@@ -289,7 +289,7 @@ amcanreturn (Relation indexRelation);
 void
 amcostestimate (PlannerInfo *root,
                 IndexPath *path,
-                RelOptInfo *outer_rel,
+                double loop_count,
                 Cost *indexStartupCost,
                 Cost *indexTotalCost,
                 Selectivity *indexSelectivity,
@@ -928,7 +928,7 @@ amrestrpos (IndexScanDesc scan);
 void
 amcostestimate (PlannerInfo *root,
                 IndexPath *path,
-                RelOptInfo *outer_rel,
+                double loop_count,
                 Cost *indexStartupCost,
                 Cost *indexTotalCost,
                 Selectivity *indexSelectivity,
@@ -958,16 +958,15 @@ amcostestimate (PlannerInfo *root,
     </varlistentry>
 
     <varlistentry>
-     <term><parameter>outer_rel</></term>
+     <term><parameter>loop_count</></term>
      <listitem>
       <para>
-       If the index is being considered for use in a join inner indexscan,
-       the planner's information about the outer side of the join.  Otherwise
-       <symbol>NULL</>.  When non-<symbol>NULL</>, some of the qual clauses
-       will be join clauses for joins
-       with this rel rather than being simple restriction clauses.  Also,
-       the cost estimator should expect that the index scan will be repeated
-       for each row of the outer rel.
+       The number of repetitions of the index scan that should be factored
+       into the cost estimates.  This will typically be greater than one when
+       considering a parameterized scan for use in the inside of a nestloop
+       join.  Note that the cost estimates should still be for just one scan;
+       a larger <parameter>loop_count</> means that it may be appropriate
+       to allow for some caching effects across multiple scans.
       </para>
      </listitem>
     </varlistentry>
@@ -1062,8 +1061,8 @@ amcostestimate (PlannerInfo *root,
   </para>
 
   <para>
-   In the join case, the returned numbers should be averages expected for
-   any one scan of the index.
+   When <parameter>loop_count</> is greater than one, the returned numbers
+   should be averages expected for any one scan of the index.
   </para>
 
   <procedure>
@@ -1121,7 +1120,7 @@ cost_qual_eval(&amp;index_qual_cost, path-&gt;indexquals, root);
 </programlisting>
 
      However, the above does not account for amortization of index reads
-     across repeated index scans in the join case.
+     across repeated index scans.
     </para>
    </step>
 
-- 
cgit v1.2.3