SPI_prepare <refpurpose>prepare a statement, without executing it yet</refpurpose> — 文を準備する。文の実行はまだ行わない
SPIPlanPtr SPI_prepare(const char *command
, intnargs
, Oid *argtypes
)
<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
を使用して長期間文を保存することもできます。
const char * command
command string コマンド文字列
int nargs
number of input parameters (<literal>$1</literal>, <literal>$2</literal>, etc.)
入力パラメータ($1
、$2
など)の数
Oid * argtypes
pointer to an array containing the <acronym>OID</acronym>s of the data types of the parameters パラメータのデータ型のOIDを持つ配列へのポインタ
<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
という名前はいくらか歴史的なものです。