同一または類似の問い合わせが繰返し実行される場合、問い合わせの計画作成を1回のみ実行することは利点がある可能性があります。SPI_prepare は問い合わせ文字列を、SPI_execp に繰返し渡すことができる実行計画に変換します。
準備済みの問い合わせは、通常の問い合わせでは定数となる場所にパラメータ($1, $2, etc) を記述することで、一般化することができます。パラメータの値は、SPI_execp が呼び出された時に指定されます。これにより、準備済み問い合わせは、パラメータがない場合に比べ、より広範囲の状況で使用できるようになります。
Note: しかし、欠点があります。プランナはパラメータに与えられる値が何であるかを理解しませんので、すべての定数が可視である単純な問い合わせで作成されるものより、問い合わせ計画の選択が悪化する可能性があります。
問い合わせがパラメータを使用する場合、その番号とデータ型は SPI_prepare の呼び出しの際に指定されなければなりません。
SPI_prepareで返されるプランは、SPI_finishが割り当てたメモリ領域を解放しますので、現在処理中のプロシージャ中でのみで使用できます。SPI_saveplanを参照してください。
成功した場合、非NULLのポインタが返ります。失敗した場合はNULLの実行プランが返ります。どちらにしてもSPI_execの戻り値と同様に、SPI_resultが設定されます。 ただし引数queryがNULLの場合、nargs < 0の場合、nargs > 0かつ引数argtypesがNULLの場合は、SPI_ERROR_ARGUMENTが設定されます。