説明

<command>PREPARE</command> creates a prepared statement. A prepared statement is a server-side object that can be used to optimize performance. When the <command>PREPARE</command> statement is executed, the specified statement is parsed, analyzed, and rewritten. When an <command>EXECUTE</command> 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. PREPAREはプリペアド文を作成します。 プリペアド文は、性能を最適化するために利用可能なサーバ側オブジェクトです。 PREPARE文を実行すると、指定された問い合わせの構文解析、書き換えが行われます。 その後、EXECUTE文が発行された際に、プリペアド文は実行計画が作成され、実行されます。 この作業の分割により構文解析作業が繰り返されることを防止でき、さらに、特定のパラメータ値に合わせた実行計画を提供することができます。

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 <literal>$1</literal>, <literal>$2</literal>, 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 <literal>unknown</literal>, the type is inferred from the context in which the parameter is first referenced (if possible). When executing the statement, specify the actual values for these parameters in the <command>EXECUTE</command> statement. Refer to <xref linkend="sql-execute"/> for more information about that. プリペアド文はパラメータ、すなわち文が実行される時に代入される値を取ることができます。 プリペアド文を作成する時には$1や$2などを使用して、位置によりパラメータを参照してください。 対応するパラメータのデータ型のリストをオプションで指定することもできます。 パラメータのデータ型の指定がない、または、unknownと宣言されている場合、型はパラメータが最初に参照される文脈より（可能ならば）推測されます。 文の実行時には、EXECUTE文内にこれらのパラメータの実際の値を指定します。 詳細はEXECUTEを参照してください。

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 <link linkend="sql-deallocate"><command>DEALLOCATE</command></link> command. プリペアド文は現在のデータベースセッションの期間中にのみ保持されます。 セッションが終了すると、プリペアド文は破棄されます。 そのため、再び利用する場合は、再作成する必要があります。 また、これは、1つのプリペアド文を同時実行中の複数のデータベースクライアントから使用することはできないことを意味します。 ただし、各クライアントが個別にプリペアド文を作成することはできます。 プリペアド文を手作業で削除するには、DEALLOCATEコマンドを使用します。

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, 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. プリペアド文は潜在的には、単一のセッションで同類の問い合わせを多数実行する場合に、パフォーマンスにおける最大の利益がえられます。 パフォーマンスの違いは、文の書き換えや実行計画が複雑なほど顕著になるでしょう。 例えば、問い合わせに多数のテーブルの結合が含まれている場合や、いくつものルールを適用しなければならない場合などが考えられます。 書き換えおよび実行計画が比較的単純で、実行コストが高い文の場合は、プリペアド文の効果はそれほど現れないでしょう。

パラメータ

注釈

A prepared statement can be executed with either a <firstterm>generic plan</firstterm> or a <firstterm>custom plan</firstterm>. 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. (Of course, if the prepared statement has no parameters, then this is moot and a generic plan is always used.) プリペアド文は、汎用的な計画または独自の計画のいずれかで実行することができます。 汎用的な計画は全実行に渡って同じであるのに対して、独自の計画はその呼出しで与えられたパラメータ値を使った特別な実行のために生成されます。 汎用的な計画の使用は計画のオーバーヘッドを回避しますが、プランナがパラメータ値の知識を使えるので、独自の計画の方がずっと効率よく実行される場合があります。 (もちろん、プリペアド文にパラメータがなければ、これは無意味で、汎用的な計画が常に使われます。)

By default (that is, when <xref linkend="guc-plan-cache-mode"/> is set to <literal>auto</literal>), the server will automatically choose 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. デフォルト(すなわち、plan_cache_modeがautoに設定されている場合)では、パラメータのあるプリペアド文に対して、汎用的な計画を使うか独自の計画を使うかを、サーバは自動的に選択します。 これに対する現在の規則は、最初の5回が独自の計画で実行され、その計画の推定コストの平均が計算される、というものです。 それから汎用的な計画が作成され、その推定コストが独自の計画のコストの平均と比較されます。 再計画を繰り返すことが望ましいと思えるほどにはそのコストが独自の計画の平均コストよりも高くなければ、その後の実行は汎用的な計画を使います。

This heuristic can be overridden, forcing the server to use either generic or custom plans, by setting <varname>plan_cache_mode</varname> to <literal>force_generic_plan</literal> or <literal>force_custom_plan</literal> 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. plan_cache_modeをforce_generic_planまたはforce_custom_planに設定して、サーバにそれぞれ汎用的な計画または独自の計画を使うように強制することで、この発見的手法を置き換えることができます。 汎用的な計画の実際のコストが独自の計画のものよりもずっと多い場合でも、汎用的な計画を選べるようになりますので、汎用的な計画のコスト推定が何らかの理由でひどく外れる場合に、この設定は主として有用です。

To examine the query plan <productname>PostgreSQL</productname> is using for a prepared statement, use <link linkend="sql-explain"><command>EXPLAIN</command></link>, for example プリペアド文に対してPostgreSQLが使用する問い合わせ計画を検証するためには、EXPLAIN、例えば

EXPLAIN EXECUTE name(parameter_values);

If a generic plan is in use, it will contain parameter symbols <literal>$<replaceable>n</replaceable></literal>, while a custom plan will have the supplied parameter values substituted into it. を使用してください。 汎用的な計画が使用される場合には、$nというパラメータ記号が含まれ、独自の計画が使用される場合は提供されたパラメータの値で置換されます。

For more information on query planning and the statistics collected by <productname>PostgreSQL</productname> for that purpose, see the <xref linkend="sql-analyze"/> documentation. 問い合わせの実行計画や問い合わせの最適化のためにPostgreSQLが収集する統計に関する詳細は、ANALYZEのドキュメントを参照してください。

Although the main point of a prepared statement is to avoid repeated parse analysis and planning of the statement, <productname>PostgreSQL</productname> 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 or their planner statistics have been updated since the previous use of the prepared statement. Also, if the value of <xref linkend="guc-search-path"/> changes from one use to the next, the statement will be re-parsed using the new <varname>search_path</varname>. (This latter behavior is new as of <productname>PostgreSQL</productname> 9.3.) These rules make use of a prepared statement semantically almost equivalent to re-submitting the same query text over and over, but with a performance benefit if no object definitions are changed, especially if the best plan remains the same across uses. An example of a case where the semantic equivalence is not perfect is that if the statement refers to a table by an unqualified name, and then a new table of the same name is created in a schema appearing earlier in the <varname>search_path</varname>, 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. プリペアド文の主要な利点は、文の解析処理と計画作成処理の繰り返しを防止することですが、PostgreSQLでは、以前にそのプリペアド文を使用してから、文の中で使用されているデータベースオブジェクトが定義（DDL）の変更を受けたり、プランナの統計が更新されたりした時は常に再解析処理と計画再作成処理を強制します。 また、一度使用してからsearch_pathの値が変わった場合も、文は新しいsearch_pathを使用して再解析されます。 （後者の振る舞いはPostgreSQL 9.3の時に追加されました。） これらの規則により、プリペアド文の使用は意味的に同じ問い合わせを繰り返し再投入することとほぼ同じになりますが、特に最善の計画が使用している間に変わらずに残る場合、オブジェクトの変更がない場合の性能という利点があります。 意味的な等価性が完全ではない場合の例は、 文が未修飾名によってテーブルを参照し、その後同じ名前のテーブルが新たにsearch_path内で前に現れるスキーマ内に作成された場合、文の中で使用されるオブジェクトには変更がありませんので、自動再解析は行われません。 しかし他の何らかの変更により強制的に再解析された場合、その後の使用では新しいテーブルが参照されるようになります。

You can see all prepared statements available in the session by querying the <link linkend="view-pg-prepared-statements"><structname>pg_prepared_statements</structname></link> system view. pg_prepared_statementsシステムビューを問い合わせることによりセッションで利用可能なプリペアド文をすべて確認することができます。

例

Create a prepared statement for an <command>INSERT</command> statement, and then execute it: INSERT文に対してプリペアド文を作成し、実行します。

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 <command>SELECT</command> statement, and then execute it: SELECT文に対してプリペアド文を作成し、実行します。

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);

In this example, the data type of the second parameter is not specified, so it is inferred from the context in which <literal>$2</literal> is used. この例では第2パラメータのデータ型が指定されていません。 このため$2が使用される文脈からデータ型が推測されます。

互換性

The SQL standard includes a <command>PREPARE</command> statement, but it is only for use in embedded SQL. This version of the <command>PREPARE</command> statement also uses a somewhat different syntax. 標準SQLにはPREPARE文が含まれていますが、埋め込みSQLでの使用に限られています。 また、標準SQLのPREPARE文では多少異なる構文が使用されます。

関連項目