説明

<function>SPI_prepare</function> creates and returns a prepared statement for the specified command, but doesn't execute the command. The prepared statement can later be executed repeatedly using <function>SPI_execute_plan</function>. SPI_prepareは指定したコマンド用の準備済み文を作成し、それを返します。 しかし、そのコマンドは実行しません。 その準備済み文はSPI_execute_planを使って後で繰り返し実行できます。

When the same or a similar command is to be executed repeatedly, it is generally advantageous to perform parse analysis only once, and might furthermore be advantageous to re-use an execution plan for the command. <function>SPI_prepare</function> converts a command string into a prepared statement that encapsulates the results of parse analysis. The prepared statement also provides a place for caching an execution plan if it is found that generating a custom plan for each execution is not helpful. 同じ、あるいは類似のコマンドが繰り返し実行される場合、一度だけ解析を計画作成を行うことには一般に利点があります。 また、コマンドの実行計画を再利用することにはさらに利点があるかも知れません。 SPI_prepareはコマンド文字列を、解析結果をカプセル化した準備済み文に変換します。 実行の度に独自計画を生成するのが役に立たないと分かった場合には、準備済み文は実行計画をキャッシュする場所も提供します。

A prepared command can be generalized by writing parameters (<literal>$1</literal>, <literal>$2</literal>, etc.) in place of what would be constants in a normal command. The actual values of the parameters are then specified when <function>SPI_execute_plan</function> is called. This allows the prepared command to be used over a wider range of situations than would be possible without parameters. プリペアドコマンドは、通常のコマンド内の定数となる場所を（$1、$2などの）パラメータで記述することで一般化することができます。 そしてパラメータの実際の値は、SPI_execute_plan が呼び出される時に指定されます。 これにより、プリペアドコマンドは、パラメータがない場合に比べ、より広範な状況で使用できるようになります。

The statement returned by <function>SPI_prepare</function> can be used only in the current invocation of the C function, since <function>SPI_finish</function> frees memory allocated for such a statement. But the statement can be saved for longer using the functions <function>SPI_keepplan</function> or <function>SPI_saveplan</function>. SPI_finishが文のために割り当てられたメモリを解放しますので、SPI_prepareで返される文は、そのC関数の現在の呼び出し内でのみ使用することができます。 しかし、関数SPI_keepplanやSPI_saveplanを使用して長期間文を保存することもできます。

引数

戻り値

<function>SPI_prepare</function> returns a non-null pointer to an <type>SPIPlan</type>, which is an opaque struct representing a prepared statement. On error, <symbol>NULL</symbol> will be returned, and <varname>SPI_result</varname> will be set to one of the same error codes used by <function>SPI_execute</function>, except that it is set to <symbol>SPI_ERROR_ARGUMENT</symbol> if <parameter>command</parameter> is <symbol>NULL</symbol>, or if <parameter>nargs</parameter> is less than 0, or if <parameter>nargs</parameter> is greater than 0 and <parameter>argtypes</parameter> is <symbol>NULL</symbol>. SPI_prepareはSPIPlanへの非NULLのポインタを返します。 ここでSPIPlanは準備済み文を表すopaque構造体です。 エラーの場合、NULLが返され、SPI_executeで使用されるエラーコードと同じコードの1つがSPI_resultに設定されます。 しかし、commandがNULLの場合や、nargsが0未満の場合、nargsが0より大きくかつargtypesがNULLの場合は、SPI_ERROR_ARGUMENTに設定されます。

注釈

If no parameters are defined, a generic plan will be created at the first use of <function>SPI_execute_plan</function>, and used for all subsequent executions as well. If there are parameters, the first few uses of <function>SPI_execute_plan</function> will generate custom plans that are specific to the supplied parameter values. After enough uses of the same prepared statement, <function>SPI_execute_plan</function> will build a generic plan, and if that is not too much more expensive than the custom plans, it will start using the generic plan instead of re-planning each time. If this default behavior is unsuitable, you can alter it by passing the <literal>CURSOR_OPT_GENERIC_PLAN</literal> or <literal>CURSOR_OPT_CUSTOM_PLAN</literal> flag to <function>SPI_prepare_cursor</function>, to force use of generic or custom plans respectively. パラメータが定義されていなければ、SPI_execute_planが最初に使用された時に一般的な計画が作成され、以降の実行すべてでも利用されます。 パラメータがあれば、始めの何回かのSPI_execute_planの使用で、与えられたパラメータの値に固有の独自計画が作成されます。 同じ準備済み文が十分に使用された後、SPI_execute_planは一般的な計画を作成し、独自計画よりもそれほど高価でなければ、毎回再計画する代わりに一般的な計画を使い始めるようになります。 このデフォルトの動作が不適切であれば、SPI_prepare_cursorにCURSOR_OPT_GENERIC_PLANまたはCURSOR_OPT_CUSTOM_PLANフラグを設定することで、それぞれ一般的な計画か独自計画を強制的に利用するよう変更できます。

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 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.) See <xref linkend="sql-prepare"/> for more information about the behavior of prepared statements. プリペアド文の主要な利点は、文の解析処理と計画作成処理の繰り返しを防止することですが、PostgreSQLでは、以前にそのプリペアド文を使用してから、文の中で使用されているデータベースオブジェクトが定義（DDL）の変更を受けた時は常に再解析処理と計画再作成処理を強制します。 また、一度使用してからsearch_pathの値が変わった場合も、文は新しいsearch_pathを使用して再解析されます。 （後者の振る舞いはPostgreSQL 9.3の時に追加されました。） プリペアド文の動作についてはPREPAREを参照してください。

This function should only be called from a connected C function. この関数は接続済みのC関数からのみ呼び出してください。

<type>SPIPlanPtr</type> is declared as a pointer to an opaque struct type in <filename>spi.h</filename>. It is unwise to try to access its contents directly, as that makes your code much more likely to break in future revisions of <productname>PostgreSQL</productname>. SPIPlanPtrはspi.h内でopaque構造体型へのポインタとして宣言されています。 たいていの場合将来のバージョンのPostgreSQLでそのコードが壊れてしまうため、この内容に直接アクセスすることは避けてください。

The name <type>SPIPlanPtr</type> is somewhat historical, since the data structure no longer necessarily contains an execution plan. そのデータ構造はもはや実行計画を含むとは限りませんので、SPIPlanPtrという名前はいくらか歴史的なものです。