@@ -127,40 +127,49 @@ PREPARE <replaceable class="parameter">name</replaceable> [ ( <replaceable class
127
127
<title>Notes</title>
128
128
129
129
<para>
130
- Prepared statements can use generic plans rather than re-planning with
131
- each set of supplied <command>EXECUTE</command> values. This occurs
132
- immediately for prepared statements with no parameters; otherwise
133
- it occurs only after five or more executions produce plans whose
134
- estimated cost average (including planning overhead) is more expensive
135
- than the generic plan cost estimate. Once a generic plan is chosen,
136
- it is used for the remaining lifetime of the prepared statement.
137
- Using <command>EXECUTE</command> values which are rare in columns with
138
- many duplicates can generate custom plans that are so much cheaper
139
- than the generic plan, even after adding planning overhead, that the
140
- generic plan might never be used.
130
+ A prepared statement can be executed with either a <firstterm>generic
131
+ plan</firstterm> or a <firstterm>custom plan</firstterm>. A generic
132
+ plan is the same across all executions, while a custom plan is generated
133
+ for a specific execution using the parameter values given in that call.
134
+ Use of a generic plan avoids planning overhead, but in some situations
135
+ a custom plan will be much more efficient to execute because the planner
136
+ can make use of knowledge of the parameter values. (Of course, if the
137
+ prepared statement has no parameters, then this is moot and a generic
138
+ plan is always used.)
141
139
</para>
142
140
143
141
<para>
144
- A generic plan assumes that each value supplied to
145
- <command>EXECUTE</command> is one of the column's distinct values
146
- and that column values are uniformly distributed. For example,
147
- if statistics record three distinct column values, a generic plan
148
- assumes a column equality comparison will match 33% of processed rows.
149
- Column statistics also allow generic plans to accurately compute the
150
- selectivity of unique columns. Comparisons on non-uniformly-distributed
151
- columns and specification of non-existent values affects the average
152
- plan cost, and hence if and when a generic plan is chosen.
142
+ By default (that is, when <xref linkend="guc-plan-cache_mode"/> is set
143
+ to <literal>auto</literal>), the server will automatically choose
144
+ whether to use a generic or custom plan for a prepared statement that
145
+ has parameters. The current rule for this is that the first five
146
+ executions are done with custom plans and the average estimated cost of
147
+ those plans is calculated. Then a generic plan is created and its
148
+ estimated cost is compared to the average custom-plan cost. Subsequent
149
+ executions use the generic plan if its cost is not so much higher than
150
+ the average custom-plan cost as to make repeated replanning seem
151
+ preferable.
152
+ </para>
153
+
154
+ <para>
155
+ This heuristic can be overridden, forcing the server to use either
156
+ generic or custom plans, by setting <varname>plan_cache_mode</varname>
157
+ to <literal>force_generic_plan</literal>
158
+ or <literal>force_custom_plan</literal> respectively.
159
+ This setting is primarily useful if the generic plan's cost estimate
160
+ is badly off for some reason, allowing it to be chosen even though
161
+ its actual cost is much more than that of a custom plan.
153
162
</para>
154
163
155
164
<para>
156
165
To examine the query plan <productname>PostgreSQL</productname> is using
157
- for a prepared statement, use <xref linkend="sql-explain"/>, e.g.
158
- <command>EXPLAIN EXECUTE</command>.
166
+ for a prepared statement, use <xref linkend="sql-explain"/>, for example
167
+ <programlisting>
168
+ EXPLAIN EXECUTE <replaceable>stmt_name</replaceable>(<replaceable>parameter_values</replaceable>);
169
+ </programlisting>
159
170
If a generic plan is in use, it will contain parameter symbols
160
- <literal>$<replaceable>n</replaceable></literal>, while a custom plan will have the
161
- supplied parameter values substituted into it.
162
- The row estimates in the generic plan reflect the selectivity
163
- computed for the parameters.
171
+ <literal>$<replaceable>n</replaceable></literal>, while a custom plan
172
+ will have the supplied parameter values substituted into it.
164
173
</para>
165
174
166
175
<para>
@@ -221,7 +230,7 @@ PREPARE usrrptplan (int) AS
221
230
EXECUTE usrrptplan(1, current_date);
222
231
</programlisting>
223
232
224
- Note that the data type of the second parameter is not specified,
233
+ In this example, the data type of the second parameter is not specified,
225
234
so it is inferred from the context in which <literal>$2</literal> is used.
226
235
</para>
227
236
</refsect1>
0 commit comments