mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

document when PREPARE uses generic plans

Browse Source 
Also explain how generic plans are created.
Link to PREPARE docs from wire-protocol prepare docs.

Reported-by: Jonathan Rogers

Discussion: https://www.postgresql.org/message-id/flat/561E749D.4090301%40socialserve.com
This commit is contained in:
Bruce Momjian 2016-06-14 16:11:46 -04:00
parent 13e7453135
commit fab9d1da4a
2 changed files with 35 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/src/sgml/libpq.sgml
View File

@ -2303,8 +2303,8 @@ PGresult *PQprepare(PGconn *conn,
<para>
<function>PQprepare</> creates a prepared statement for later
execution with <function>PQexecPrepared</>. This feature allows
commands that will be used repeatedly to be parsed and planned just
once, rather than each time they are executed.
commands to be executed repeatedly without being parsed and
planned each time; see <xref linkend="SQL-PREPARE"> for details.
<function>PQprepare</> is supported only in protocol 3.0 and later
connections; it will fail when using protocol 2.0.
</para>

48
doc/src/sgml/ref/prepare.sgml
View File

@ -70,11 +70,11 @@ PREPARE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class
</para>
<para>
Prepared statements have the largest performance advantage when a
single session is being used to execute a large number of similar
Prepared statements potentially have the largest performance advantage
when a single session is being used to execute a large number of similar
statements. The performance difference will be particularly
significant if the statements are complex to plan or rewrite, for
example, if the query involves a join of many tables or requires
significant if the statements are complex to plan or rewrite, e.g.
if the query involves a join of many tables or requires
the application of several rules. If the statement is relatively simple
to plan and rewrite but relatively expensive to execute, the
performance advantage of prepared statements will be less noticeable.
@ -123,26 +123,44 @@ PREPARE <replaceable class="PARAMETER">name</replaceable> [ ( <replaceable class
</variablelist>
</refsect1>
<refsect1>
<refsect1 id="SQL-PREPARE-notes">
<title>Notes</title>
<para>
If a prepared statement is executed enough times, the server may eventually
decide to save and re-use a generic plan rather than re-planning each time.
This will occur immediately if the prepared statement has no parameters;
otherwise it occurs only if the generic plan appears to be not much more
expensive than a plan that depends on specific parameter values.
Typically, a generic plan will be selected only if the query's performance
is estimated to be fairly insensitive to the specific parameter values
supplied.
Prepared statements can use generic plans rather than re-planning with
each set of supplied <command>EXECUTE</command> values. This occurs
immediately for prepared statements with no parameters; otherwise
it occurs only after five or more executions produce plans whose
estimated cost average (including planning overhead) is more expensive
than the generic plan cost estimate. Once a generic plan is chosen,
it is used for the remaining lifetime of the prepared statement.
Using <command>EXECUTE</command> values which are rare in columns with
many duplicates can generate custom plans that are so much cheaper
than the generic plan, even after adding planning overhead, that the
generic plan might never be used.
</para>
<para>
A generic plan assumes that each value supplied to
<command>EXECUTE</command> is one of the column's distinct values
and that column values are uniformly distributed. For example,
if statistics record three distinct column values, a generic plan
assumes a column equality comparison will match 33% of processed rows.
Column statistics also allow generic plans to accurately compute the
selectivity of unique columns. Comparisons on non-uniformly-distributed
columns and specification of non-existent values affects the average
plan cost, and hence if and when a generic plan is chosen.
</para>
<para>
To examine the query plan <productname>PostgreSQL</productname> is using
for a prepared statement, use <xref linkend="sql-explain">.
for a prepared statement, use <xref linkend="sql-explain">, e.g.
<command>EXPLAIN EXECUTE</>.
If a generic plan is in use, it will contain parameter symbols
<literal>$<replaceable>n</></literal>, while a custom plan will have the
current actual parameter values substituted into it.
supplied parameter values substituted into it.
The row estimates in the generic plan reflect the selectivity
computed for the parameters.
</para>
<para>