37.8. カーソル

37.8.2.1. OPEN FOR SELECT

OPEN unbound-cursor FOR SELECT ...;

カーソル変数は開かれ、実行するよう指定した問い合わせが付与されます。 既に開いたカーソルを開くことはできず、また、アンバウンドカーソルとして(つまり、単なるrefcursor変数として)宣言されていなければなりません。 このSELECT問い合わせは、他のPL/pgSQLのSELECT文と同様の方法で扱われます。 PL/pgSQLの変数名は置き換えられ、問い合わせ計画は再利用できるようにキャッシュされます。

以下に例を示します。

OPEN curs1 FOR SELECT * FROM foo WHERE key = mykey;

37.8.2.2. OPEN FOR EXECUTE

OPEN unbound-cursor FOR EXECUTE query-string;

カーソル変数は開かれ、実行するよう指定した問い合わせが付与されます。 既に開いたカーソルを開くことはできず、また、アンバウンドカーソルとして(つまり、単なるrefcursor変数として)宣言されていなければなりません。 問い合わせは、EXECUTEコマンドと同じ方法による文字列式として指定されます。 通常と同様に、これにより、次回に実行する際に違った問い合わせをすることができる柔軟性が得られます。

以下に例を示します。

OPEN curs1 FOR EXECUTE ''SELECT * FROM '' || quote_ident($1);

37.8.2.3. バウンドカーソルを開く

OPEN bound-cursor [ ( argument_values ) ];

宣言時に問い合わせがバウンドされたカーソル変数を開くために使用されるOPENの形式です。 既に開いたカーソルを開くことはできません。 実引数の評価式のリストはカーソルが引数をとるものと宣言された場合にのみ現れます。 これらの値は、問い合わせの中で置き換えられます。 バウンドカーソルの問い合わせ計画は常にキャッシュ可能とみなされます。 この場合、EXECUTEと等価なものはありません。

例

OPEN curs2;
OPEN curs3(42);

37.8.3.1. FETCH

FETCH cursor INTO target;

FETCHはSELECT INTOと同様に、カーソルから次の行を抽出し、対象に格納します。 対象とは、行変数、レコード変数、または単純な変数をコンマで区切ったリストです。 SELECT INTOの場合と同様、特殊なFOUND変数を検査することで、行が入手できたかどうかを確認することができます。

例

FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo, bar, baz;

37.8.3.2. CLOSE

CLOSE cursor;

CLOSEはポータルの背後のカーソルを閉じます。 これを使用してトランザクションの終りよりも前にリソースを解放することができ、また、カーソル変数を解放し、再度開くことができます。

例

CLOSE curs1;

37.8.3.3. カーソルを返す

PL/pgSQL関数では、呼び出し元にカーソルを返すことができます。 この方法は、関数から複数行または複数列を返す場合、特にその結果集合が非常に大きい場合に使用します。 これを行なうには、関数は、カーソルを開き、呼び出し元にカーソル名を返します(もしくは、もし呼出し元でポータル名が判っていれば、単純に指定されたポータル名を使用してカーソルを開きます)。 これにより、呼び出し元は、カーソルから行を取り出すことができるようになります。 カーソルは、呼び出し元で閉じることができます。または、トランザクションが終了した際に自動的に閉じられます。

カーソル用のポータル名は、プログラマが指定するか、または自動で生成されます。 ポータル名を指定するには、開く前に、単にrefcursor変数に文字列を代入します。 refcursor変数の文字列値はOPENによって、背後のポータル名として使用されます。 しかし、refcursor変数がNULLの場合、OPENは自動的に既存のポータルと競合しない名前を生成し、それをrefcursor変数に代入します。

以下の例は、呼び出し元でカーソル名を指定する方法を示しています。

CREATE TABLE test (col text);
INSERT INTO test VALUES ('123');

CREATE FUNCTION reffunc(refcursor) RETURNS refcursor AS '
BEGIN
    OPEN $1 FOR SELECT col FROM test;
    RETURN $1;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT reffunc('funccursor');
FETCH ALL IN funccursor;
COMMIT;

以下の例では、自動カーソル名生成を使用しています。

CREATE FUNCTION reffunc2() RETURNS refcursor AS '
DECLARE
    ref refcursor;
BEGIN
    OPEN ref FOR SELECT col FROM test;
    RETURN ref;
END;
' LANGUAGE plpgsql;

BEGIN;
SELECT reffunc2();
  
      reffunc2      
--------------------
 <unnamed cursor 1>
(1 row)

FETCH ALL IN "<unnamed cursor 1>";
COMMIT;