From 40347064be613ed526683782798e52625efcf312 Mon Sep 17 00:00:00 2001 From: Mel Kiyama Date: Fri, 13 Mar 2020 09:33:07 -0700 Subject: [PATCH] docs - new GUC plan_cache_mode (#9734) * docs - new GUC plan_cache_mode --Add GUC --update PREPARE reference, Notes section Also, minor fix in guc_category_list * docs - minor edits --- .../dita/ref_guide/config_params/guc-list.xml | 45 +++++ .../config_params/guc_category-list.xml | 4 +- .../config_params/guc_config.ditamap | 2 +- .../dita/ref_guide/sql_commands/PREPARE.xml | 171 ++++++++++++------ 4 files changed, 163 insertions(+), 59 deletions(-) diff --git a/gpdb-doc/dita/ref_guide/config_params/guc-list.xml b/gpdb-doc/dita/ref_guide/config_params/guc-list.xml index 895629fa23..fa2dbb8294 100644 --- a/gpdb-doc/dita/ref_guide/config_params/guc-list.xml +++ b/gpdb-doc/dita/ref_guide/config_params/guc-list.xml @@ -458,6 +458,10 @@
  • optimizer_use_gpdb_allocators
    • +
  • +

    +

    +
    • @@ -7419,6 +7423,47 @@ + + plan_cache_mode + +

    Prepared statements (either explicitly prepared or implicitly generated, for example by + PL/pgSQL) can be executed using custom or generic plans. Custom plans are + created for each execution using its specific set of parameter values, while generic plans + do not rely on the parameter values and can be re-used across executions. The use of a + generic plan saves planning time, but if the ideal plan depends strongly on the parameter + values, then a generic plan might be inefficient. The choice between these options is + normally made automatically, but it can be overridden by setting the + plan_cache_mode parameter. If the prepared statement has no parameters, a + generic plan is always used.

    +

    The allowed values are auto (the default), + force_custom_plan and force_generic_plan. This setting + is considered when a cached plan is to be executed, not when it is prepared. For more + information see .

    +

    The parameter can be set for a database system, an individual database, a session, or a + query.

    + + + + + + + + Value Range + Default + Set Classifications + + + + + auto

    force_custom_plan

    force_generic_plan

     + auto + master

    session

    reload

     +     + + +
    + +     pljava_classpath diff --git a/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml b/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml index 07ef9af6f1..770738ae8d 100644 --- a/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml +++ b/gpdb-doc/dita/ref_guide/config_params/guc_category-list.xml @@ -23,9 +23,6 @@
    • -
  • - -
    • @@ -660,6 +657,7 @@

    gp_max_slices

    +

    plan_cache_mode

         diff --git a/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap b/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap index e5fa20d09a..09132974d0 100644 --- a/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap +++ b/gpdb-doc/dita/ref_guide/config_params/guc_config.ditamap @@ -11,7 +11,6 @@ - @@ -235,6 +234,7 @@ + diff --git a/gpdb-doc/dita/ref_guide/sql_commands/PREPARE.xml b/gpdb-doc/dita/ref_guide/sql_commands/PREPARE.xml index 1c5a3ec660..a9f6a7622c 100644 --- a/gpdb-doc/dita/ref_guide/sql_commands/PREPARE.xml +++ b/gpdb-doc/dita/ref_guide/sql_commands/PREPARE.xml @@ -1,53 +1,97 @@ -PREPARE

    Prepare a statement for execution.

    SynopsisPREPARE name [ (datatype [, ...] ) ] AS statement
    Description -

    PREPARE creates a prepared statement. A prepared - statement is a server-side object that can be used to optimize - performance. When the PREPARE statement is - executed, the specified statement is parsed, analyzed, and rewritten. - When an EXECUTE command is subsequently - issued, the prepared statement is planned and executed. This division - of labor avoids repetitive parse analysis work, while allowing - the execution plan to depend on the specific parameter values supplied.

    -

    Prepared statements can take parameters: values that are substituted into the statement when it - is executed. When creating the prepared statement, refer to parameters by position, using - $1, $2, etc. A corresponding list of parameter data + + PREPARE + +

    Prepare a statement for execution.

    +
    + Synopsis + PREPARE name [ (datatype [, ...] ) ] AS statement +
    +
    + Description +

    PREPARE creates a prepared statement. A prepared statement is a + server-side object that can be used to optimize performance. When the + PREPARE statement is executed, the specified statement is parsed, + analyzed, and rewritten. When an EXECUTE command is subsequently issued, + the prepared statement is planned and executed. This division of labor avoids repetitive + parse analysis work, while allowing the execution plan to depend on the specific parameter + values supplied.

    +

    Prepared statements can take parameters, values that are substituted into the statement + when it is executed. When creating the prepared statement, refer to parameters by position, + using $1, $2, etc. A corresponding list of parameter data types can optionally be specified. When a parameter's data type is not specified or is declared as unknown, the type is inferred from the context in which the parameter is first used (if possible). When executing the statement, specify the actual values for these - parameters in the EXECUTE statement.

    Prepared statements only last for the duration of the current database session. When the session - ends, the prepared statement is forgotten, so it must be recreated before being used again. - This also means that a single prepared statement cannot be used by multiple simultaneous - database clients; however, each client can create their own prepared statement to use. - Prepared statements can be manually cleaned up using the command.

    Prepared statements 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 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.

    ParametersnameAn arbitrary name given to this particular prepared statement. It -must be unique within a single session and is subsequently used to execute -or deallocate a previously prepared statement.datatypeThe data type of a parameter to the prepared statement. If the data type of a particular - parameter is unspecified or is specified as unknown, it will be inferred from the - context in which the parameter is first used. To refer to the parameters in the prepared - statement itself, use $1, $2, etc. statementAny SELECT, INSERT, UPDATE, -DELETE, or VALUES statement.
    Notes -

    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.

    -

    To examine the query plan Greenplum Database is using for a prepared statement, use EXPLAIN. If a generic plan is in use, it will contain - parameter symbols $n, while a custom plan will have the - current actual parameter values substituted into it.

    -

    For more information on query planning and the statistics collected by Greenplum Database for - that purpose, see the ANALYZE documentation.

    -

    Although the main point of a prepared statement is to avoid repeated parse analysis and + parameters in the EXECUTE statement.

    +

    Prepared statements only last for the duration of the current database session. When the + session ends, the prepared statement is forgotten, so it must be recreated before being used + again. This also means that a single prepared statement cannot be used by multiple + simultaneous database clients; however, each client can create their own prepared statement + to use. Prepared statements can be manually cleaned up using the command.

    +

    Prepared statements 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 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.

    +
    +
    + Parameters + + + name + An arbitrary name given to this particular prepared statement. It must be unique + within a single session and is subsequently used to execute or deallocate a previously + prepared statement. + + + datatype + The data type of a parameter to the prepared statement. If the data type of a + particular parameter is unspecified or is specified as unknown, it will be inferred from + the context in which the parameter is first used. To refer to the parameters in the + prepared statement itself, use $1, $2, etc. + + + statement + Any SELECT, INSERT, UPDATE, + DELETE, or VALUES statement. + + +
    +
    + Notes +

    A prepared statement can be executed with either a generic plan or a custom + plan. A generic plan is the same across all executions, while a custom plan is + generated for a specific execution using the parameter values given in that call. Use of a + generic plan avoids planning overhead, but in some situations a custom plan will be much + more efficient to execute because the planner can make use of knowledge of the parameter + values. If the prepared statement has no parameters, a generic plan is always used.

    +

    By default (with the default value, auto, for the server configuration + parameter plan_cache_mode), the server automatically chooses whether to use a + generic or custom plan for a prepared statement that has parameters. The current rule for + this is that the first five executions are done with custom plans and the average estimated + cost of those plans is calculated. Then a generic plan is created and its estimated cost is + compared to the average custom-plan cost. Subsequent executions use the generic plan if its + cost is not so much higher than the average custom-plan cost as to make repeated replanning + seem preferable.

    +

    This heuristic can be overridden, forcing the server to use either generic or custom plans, + by setting plan_cache_mode to force_generic_plan or + force_custom_plan respectively. This setting is primarily useful if the + generic plan's cost estimate is badly off for some reason, allowing it to be chosen even + though its actual cost is much more than that of a custom plan.

    +

    To examine the query plan Greenplum Database is using for a prepared statement, use + EXPLAIN, for + example

    + EXPLAIN EXECUTE <name>(<parameter_values>); +

    If a generic plan is in use, it will contain parameter symbols $n, while a + custom plan will have the supplied parameter values substituted into it.

    +

    For more information on query planning and the statistics collected by Greenplum Database + for that purpose, see the ANALYZE documentation.

    +

    Although the main point of a prepared statement is to avoid repeated parse analysis and planning of the statement, Greenplum will force re-analysis and re-planning of the statement before using it whenever database objects used in the statement have undergone definitional (DDL) changes since the previous use of the prepared statement. Also, if the value of @@ -60,16 +104,33 @@ or deallocate a previously prepared statement.search_path, no automatic re-parse will occur since no object used in the statement changed. However, if some other change forces a re-parse, the - new table will be referenced in subsequent uses.

    You can see all prepared statements available in the session by querying the - pg_prepared_statements system view.

    Examples

    Create a prepared statement for an INSERT statement, -and then execute it:

    PREPARE fooplan (int, text, bool, numeric) AS INSERT INTO + new table will be referenced in subsequent uses.

    +

    You can see all prepared statements available in the session by querying the + pg_prepared_statements system view.

    +
    +
    + Examples +

    Create a prepared statement for an INSERT statement, and then execute + it:

    + PREPARE fooplan (int, text, bool, numeric) AS INSERT INTO foo VALUES($1, $2, $3, $4); -EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00);

    Create a prepared statement for a SELECT statement, and -then execute it. Note that the data type of the second parameter is not -specified, so it is inferred from the context in which $2 -is used:

    PREPARE usrrptplan (int) AS SELECT * FROM users u, logs l +EXECUTE fooplan(1, 'Hunter Valley', 't', 200.00); +

    Create a prepared statement for a SELECT statement, and then execute it. + Note that the data type of the second parameter is not specified, so it is inferred from the + context in which $2 is used:

    + PREPARE usrrptplan (int) AS SELECT * FROM users u, logs l WHERE u.usrid=$1 AND u.usrid=l.usrid AND l.date = $2; -EXECUTE usrrptplan(1, current_date);
    Compatibility

    The SQL standard includes a PREPARE statement, but -it is only for use in embedded SQL. This version of the PREPARE -statement also uses a somewhat different syntax.

    See Also

    ,

    +EXECUTE usrrptplan(1, current_date); +
    +
    + Compatibility +

    The SQL standard includes a PREPARE statement, but it can only be used in + embedded SQL, and it uses a different syntax.

    +
    +
    + See Also +

    , +

    +
    + +     -- GitLab