PostgreSQL 7.3 Documentation
PrevNext

SPI_exec

Name

SPI_exec -- 実行計画（パーサー＋プランナ＋オプティマイザ）を生成し、問い合わせを実行します。

Synopsis

SPI_exec(query, tcount)

入力

char *query

問い合わせ計画を含む文字列

int tcount

返されるタプルの最大数

出力

int

未接続なプロシージャから呼び出された場合SPI_ERROR_UNCONNECTEDです。
引数queryがNULLまたはtcount < 0の場合SPI_ERROR_ARGUMENT です。
未接続なプロシージャの場合 SPI_ERROR_UNCONNECTED です。
COPY TO/FROM stdinの場合 SPI_ERROR_COPY です。
DECLARE/CLOSE CURSOR、FETCHの場合 SPI_ERROR_CURSOR です。
BEGIN/ABORT/ENDの場合SPI_ERROR_TRANSACTION です。
未知の問い合わせタイプの場合SPI_ERROR_OPUNKNOWNです。 （これは起こるべきではありません）

問い合わせの実行が成功した場合、以下のような (負ではない) 値のうち、いずれかが返ります。

何らかのユーティリティ (たとえば CREATE TABLE ...) が実行された場合 SPI_OK_UTILITY です。
SELECT (ただし SELECT ... INTO 以外) が実行された場合 SPI_OK_SELECT です。
SELECT ... INTOが実行された場合 SPI_OK_SELINTO です。
INSERT（またはINSERT ... SELECT）が実行された場合 SPI_OK_INSERT です。
DELETEが実行された場合 SPI_OK_DELETE です。
UPDATEが実行された場合 SPI_OK_UPDATE です。

説明

SPI_execは、実行計画（パーサー＋プランナ＋オプティマイザ）を生成し、tcountタプルの分の問い合わせを実行します。

使用方法

接続済みのプロシージャからのみこの関数を呼び出してください。tcountが0ならば、問い合わせスキャンが返したすべてのタプルについて問い合わせを行います。tcount > 0とすることで、問い合わせの対象となるタプルの数を(LIMIT句とほぼ同様に)制限することができます。たとえば、以下の場合は、最大 5 個のタプルをテーブルに挿入することができます。 

SPI_exec ("INSERT INTO tab SELECT * FROM tab", 5);

問い合わせの実行が成功した場合、負ではない値が返ります。

Note: 1個の文字列の中に複数の問い合わせを入れて渡したり、RULEシステムによって複数の問い合わせに書き換えられる可能性のある文字列を渡しても構いません。SPI_execは最後に実行された問い合わせの結果を返します。

実際に（最後の）問い合わせの処理対象となったタプルの数は（SPI_OK_UTILITYでない限り）グローバル変数SPI_processedに設定されます。 もしSPI_OK_SELECTが返され、SPI_processed > 0ならば、グローバルなポインタであるSPITupleTable *SPI_tuptableというポインタを使って、結果のタプルにアクセスできます。

SPI_execは次のような（負の）値を返す可能性があります。

引数queryがNULLまたはtcount < 0の場合SPI_ERROR_ARGUMENT です。
未接続なプロシージャの場合 SPI_ERROR_UNCONNECTED です。
COPY TO/FROM stdinの場合 SPI_ERROR_COPY です。
DECLARE/CLOSE CURSOR、FETCHの場合 SPI_ERROR_CURSOR です。
BEGIN/ABORT/ENDの場合SPI_ERROR_TRANSACTION です。
未知の問い合わせタイプの場合SPI_ERROR_OPUNKNOWNです。 （これは起こるべきではありません）

構造

もしSPI_OK_SELECTが返され、SPI_processed > 0である場合、グローバルポインタ SPITupleTable *SPI_tuptableを使って選択されたタプルにアクセスすることが可能です。

構造体SPITupleTableはspi.hの中で定義されています。 

   typedef struct
   {
       MemoryContext tuptabcxt;    /* 結果タプルのメモリコンテキスト */
       uint32      alloced;        /* 割り当てられた値の数 */
       uint32      free;           /* 解放された値の数 */
       TupleDesc   tupdesc;        /* タプル記述子 */
       HeapTuple  *vals;           /* タプル */
   } SPITupleTable;

vals は、タプルへのポインタの配列です (有効なエントリ数は SPI_processed によって与えられます)。 tupdesc は、タプルを扱う SPI 関数へ渡すことのできるタプル記述子です。 tuptabcxt、alloced、free は内部用のフィールドであり、SPI 呼び出し側での使用を目的としたものではありません。

Note: 関数SPI_exec、SPI_execpおよびSPI_prepareは、SPI_processedとSPI_tuptableの両方を変更します(ポインタのみで、構造体の内容ではありません)。SPI_exec や SPI_execp の結果を後の呼び出しで使用することが必要ならば、この2つのグローバル変数をプロシージャのローカル変数に保存してください。

SPI_finish は、現在のプロシージャで割り当てられた、全てのSPITupleTablesを解放します。SPI_freetuptable を呼び出すことで、使用しなくなった、特定の結果テーブルを前もって解放することができます。

PrevHomeNext
SPI_finishUpSPI_prepare