説明

<function>SPI_execute</function> executes the specified SQL command for <parameter>count</parameter> rows. If <parameter>read_only</parameter> is <literal>true</literal>, the command must be read-only, and execution overhead is somewhat reduced. SPI_executeは指定したSQLコマンドを、count行分実行します。 read_onlyがtrueの場合、そのコマンドは読み取りのみでなければなりませんが、多少のオーバーヘッドが削減されます。

This function can only be called from a connected C function. この関数は接続済みのC関数からのみ呼び出し可能です。

If <parameter>count</parameter> is zero then the command is executed for all rows that it applies to. If <parameter>count</parameter> is greater than zero, then no more than <parameter>count</parameter> rows will be retrieved; execution stops when the count is reached, much like adding a <literal>LIMIT</literal> clause to the query. For example, countが0の場合、そのコマンドを、適用される全ての行に対して実行します。 countが0より多ければ、countを超えない数の行が取り出されます。 問い合わせにLIMIT句と追加するの同じように、countに達すれば、実行は止まります。 例えば、

SPI_execute("SELECT * FROM foo", true, 5);

will retrieve at most 5 rows from the table. Note that such a limit is only effective when the command actually returns rows. For example, は、テーブルから多くても5行しか取り出しません。 この制限はコマンドが実際に行を返した場合にのみ有効なことに注意して下さい。 例えば

SPI_execute("INSERT INTO foo SELECT * FROM bar", false, 5);

inserts all rows from <structname>bar</structname>, ignoring the <parameter>count</parameter> parameter. However, with は、countパラメータを無視して、barからすべての行を挿入します。 しかし、

SPI_execute("INSERT INTO foo SELECT * FROM bar RETURNING *", false, 5);

at most 5 rows would be inserted, since execution would stop after the fifth <literal>RETURNING</literal> result row is retrieved. は、5番目のRETURNINGの結果行を取り出した後に実行が止まりますので、多くても5行を挿入するだけです。

You can pass multiple commands in one string; <function>SPI_execute</function> returns the result for the command executed last. The <parameter>count</parameter> limit applies to each command separately (even though only the last result will actually be returned). The limit is not applied to any hidden commands generated by rules. 複数のコマンドを1つの文字列として渡すことができます。 SPI_executeは最後に実行したコマンドの結果を返します。 count制限は（最後の結果が返されただけだとしても）それぞれのコマンドに独立に適用されます。 この制限はルールによって生成される隠れたコマンドには適用されません。

When <parameter>read_only</parameter> is <literal>false</literal>, <function>SPI_execute</function> increments the command counter and computes a new <firstterm>snapshot</firstterm> before executing each command in the string. The snapshot does not actually change if the current transaction isolation level is <literal>SERIALIZABLE</literal> or <literal>REPEATABLE READ</literal>, but in <literal>READ COMMITTED</literal> mode the snapshot update allows each command to see the results of newly committed transactions from other sessions. This is essential for consistent behavior when the commands are modifying the database. read_onlyがfalseの場合、文字列内の各コマンドを実行する前にSPI_executeはコマンドカウンタを増分し、新しいスナップショットを作成します。 このスナップショットは、現在のトランザクション分離レベルがSERIALIZABLEまたはREPEATABLE READの場合は変更されません。 しかし、READ COMMITTEDモードでは、このスナップショットは更新され、他のセッションで新しくコミットされたトランザクションの結果を各コマンドから参照できます。 これは、そのコマンドがデータベースを変更する場合、一貫性の維持に重要です。

When <parameter>read_only</parameter> is <literal>true</literal>, <function>SPI_execute</function> does not update either the snapshot or the command counter, and it allows only plain <command>SELECT</command> commands to appear in the command string. The commands are executed using the snapshot previously established for the surrounding query. This execution mode is somewhat faster than the read/write mode due to eliminating per-command overhead. It also allows genuinely <firstterm>stable</firstterm> functions to be built: since successive executions will all use the same snapshot, there will be no change in the results. read_onlyがtrueの場合は、SPI_executeはスナップショットもコマンドカウンタも更新しません。 さらに、普通のSELECTコマンドのみをコマンド文字列内に記述することができます。 このコマンドは、その前後の問い合わせによって事前に確立済みのスナップショットを使用して実行されます。 この実行モードは読み書きモードよりもコマンドごとのオーバーヘッドが省略される分多少高速です。 また、これにより本当に安定（stable）な関数を構築することができます。 つまり、連続した実行は全て同じスナップショットを使用しますので、結果は変わることがないということです。

It is generally unwise to mix read-only and read-write commands within a single function using SPI; that could result in very confusing behavior, since the read-only queries would not see the results of any database updates done by the read-write queries. 一般的に、SPIを使用する1つの関数内で読み取りのみコマンドと読み書きコマンドを混在させることは勧めません。 読み取りのみの問い合わせでは、読み書き問い合わせでなされたデータベースの更新結果を参照しないため、非常に混乱した動作に陥ることがあります。

The actual number of rows for which the (last) command was executed is returned in the global variable <varname>SPI_processed</varname>. If the return value of the function is <symbol>SPI_OK_SELECT</symbol>, <symbol>SPI_OK_INSERT_RETURNING</symbol>, <symbol>SPI_OK_DELETE_RETURNING</symbol>, <symbol>SPI_OK_UPDATE_RETURNING</symbol>, or <symbol>SPI_OK_MERGE_RETURNING</symbol>, then you can use the global pointer <literal>SPITupleTable *SPI_tuptable</literal> to access the result rows. Some utility commands (such as <command>EXPLAIN</command>) also return row sets, and <literal>SPI_tuptable</literal> will contain the result in these cases too. Some utility commands (<command>COPY</command>, <command>CREATE TABLE AS</command>) don't return a row set, so <literal>SPI_tuptable</literal> is NULL, but they still return the number of rows processed in <varname>SPI_processed</varname>. （最後の）コマンドが実行した実際の行数は、SPI_processedグローバル変数に返されます。 関数の戻り値がSPI_OK_SELECT、SPI_OK_INSERT_RETURNING、SPI_OK_DELETE_RETURNING、SPI_OK_UPDATE_RETURNINGまたはSPI_OK_MERGE_RETURNINGの場合、SPITupleTable *SPI_tuptableグローバルポインタを使用して、結果の行にアクセスすることができます。 また、一部のユーティリティコマンド（EXPLAINなど）は行セットを返しますが、この場合もSPI_tuptableにはその結果が含まれます。 一部のユーティリティコマンド（COPY, CREATE TABLE AS）は行セットを返しません。 このためSPI_tuptableはNULLですが、SPI_processedの中で処理行数を返します。

The structure <structname>SPITupleTable</structname> is defined thus: SPITupleTable構造体は以下のように定義されています。

typedef struct SPITupleTable
{

    /* Public members */
    TupleDesc   tupdesc;        /* tuple descriptor */
    HeapTuple  *vals;           /* array of tuples */
    uint64      numvals;        /* number of valid tuples */

    /* 公開メンバ */
    TupleDesc   tupdesc;        /* タプル記述子 */
    HeapTuple  *vals;           /* タプルの配列 */
    uint64      numvals;        /* 有効なタプルの数 */


    /* Private members, not intended for external callers */
    uint64      alloced;        /* allocated length of vals array */
    MemoryContext tuptabcxt;    /* memory context of result table */
    slist_node  next;           /* link for internal bookkeeping */
    SubTransactionId subid;     /* subxact in which tuptable was created */

    /* 非公開メンバ、外部呼び出し側のためのものではない */
    uint64      alloced;        /* vals配列に割り当てられた長さ */
    MemoryContext tuptabcxt;    /* 結果テーブルのメモリコンテキスト */
    slist_node  next;           /* 内部情報のためのリンク */
    SubTransactionId subid;     /* SPITupleTableが生成されたサブトランザクション */
} SPITupleTable;

The fields <structfield>tupdesc</structfield>, <structfield>vals</structfield>, and <structfield>numvals</structfield> can be used by SPI callers; the remaining fields are internal. <structfield>vals</structfield> is an array of pointers to rows. The number of rows is given by <structfield>numvals</structfield> (for somewhat historical reasons, this count is also returned in <varname>SPI_processed</varname>). <structfield>tupdesc</structfield> is a row descriptor which you can pass to SPI functions dealing with rows. フィールドtupdesc、vals、numvalsはSPIの呼び出し側で使えます。残りのフィールドは内部のものです。 valsは行へのポインタの配列です。 行数はnumvalsで与えられます(ちょっとした歴史的理由により、この数はSPI_processedでも返されます)。 tupdescは、行を扱うSPI関数に渡すことのできる行記述子です。

<function>SPI_finish</function> frees all <structname>SPITupleTable</structname>s allocated during the current C function. You can free a particular result table earlier, if you are done with it, by calling <function>SPI_freetuptable</function>. SPI_finishは、現在のC関数で割り当てられたSPITupleTableをすべて解放します。 SPI_freetuptableを呼び出して解放する場合、特定の結果テーブルを早めに解放することができます。

引数

戻り値

If the execution of the command was successful then one of the following (nonnegative) values will be returned: コマンドの実行に成功した場合、以下のいずれかの（非負の）値が返されます。

On error, one of the following negative values is returned: エラーの場合、以下のいずれかの負の値が返されます。

注釈

All SPI query-execution functions set both <varname>SPI_processed</varname> and <varname>SPI_tuptable</varname> (just the pointer, not the contents of the structure). Save these two global variables into local C function variables if you need to access the result table of <function>SPI_execute</function> or another query-execution function across later calls. SPI問い合わせ実行関数はすべてSPI_processedとSPI_tuptableの両方を変更します（ポインタのみで、構造体の内容は変更しません）。 SPI_execや他の問い合わせ実行関数の結果テーブルを後の呼び出しでまたがってアクセスしたいのであれば、これら2つのグローバル変数を局所的なプロシージャ変数に保存してください。