説明

SPI_prepareは指定したコマンド用の準備済み文を作成し、それを返します。 しかし、そのコマンドは実行しません。 その準備済み文はSPI_execute_planを使って後で繰り返し実行できます。

同じ、あるいは類似のコマンドが繰り返し実行される場合、一度だけ解析を計画作成を行うことには一般に利点があります。 また、コマンドの実行計画を再利用することにはさらに利点があるかも知れません。 SPI_prepareはコマンド文字列を、解析結果をカプセル化した準備済み文に変換します。 実行の度に独自計画を生成するのが役に立たないと分かった場合には、準備済み文は実行計画をキャッシュする場所も提供します。

プリペアドコマンドは、通常のコマンド内の定数となる場所を（$1、$2などの）パラメータで記述することで一般化することができます。 そしてパラメータの実際の値は、SPI_execute_plan が呼び出される時に指定されます。 これにより、プリペアドコマンドは、パラメータがない場合に比べ、より広範な状況で使用できるようになります。

SPI_finishは文用に割り当てられたメモリを解放しますので、SPI_prepareで返される文は、そのプロシージャの現在の呼び出し内でのみ使用することができます。 しかし、関数SPI_keepplanやSPI_saveplanを使用して長期間文を保存することもできます。

引数

戻り値

SPI_prepareはSPIPlanへの非NULLのポインタを返します。 ここでSPIPlanは準備済み文を表すopaque構造体です エラーの場合、NULLが返され、SPI_executeで使用されるエラーコードと同じコードの1つがSPI_resultに設定されます。 しかし、commandがNULLの場合や、nargsが0未満の場合、nargsが0より大きくかつargtypesがNULLの場合は、SPI_ERROR_ARGUMENTに設定されます。

注意

パラメータが定義されていなければ、SPI_execute_planが最初に使用された時に一般的な計画が作成され、以降の実行すべてでも利用されます。 パラメータがあれば、始めの何回かのSPI_execute_planの使用で、与えられたパラメータの値に固有の独自計画が作成されます。 同じ準備済み文が十分に使用された後、SPI_execute_planは一般的な計画を作成し、独自計画よりもそれほど高価でなければ、毎回再計画する代わりに一般的な計画を使い始めるようになります。 このデフォルトの動作が不適切であれば、SPI_prepare_cursorにCURSOR_OPT_GENERIC_PLANまたはCURSOR_OPT_CUSTOM_PLANフラグを設定することで、それぞれ一般的な計画か独自計画を強制的に利用するよう変更できます。

プリペアド文の主要な利点は、文の解析処理と計画作成処理の繰り返しを防止することですが、PostgreSQLでは、以前にそのプリペアド文を使用してから、文の中で使用されているデータベースオブジェクトが定義（DDL）の変更を受けた時は常に再解析処理と計画再作成処理を強制します。 また、一度使用してからsearch_pathの値が変わった場合も、文は新しいsearch_pathを使用して再解析されます。 （後者の振る舞いはPostgreSQL 9.3の時に追加されました。） プリペアド文の動作についてはPREPAREを参照してください。

この関数は接続済みのプロシージャからのみ呼び出してください。

SPIPlanPtrはspi.h内でopaque構造体型へのポインタとして宣言されています。 たいていの場合将来のバージョンのPostgreSQLでそのコードが壊れてしまうため、この内容に直接アクセスすることは避けてください。

そのデータ構造はもはや実行計画を含むとは限りませんので、SPIPlanPtrという名前はいくらか歴史的なものです。