OPEN unbound_cursorvar [ [ NO ] SCROLL ] FOR query;

The cursor variable is opened and given the specified query to execute. The cursor cannot be open already, and it must have been declared as an unbound cursor variable (that is, as a simple <type>refcursor</type> variable). The query must be a <command>SELECT</command>, or something else that returns rows (such as <command>EXPLAIN</command>). The query is treated in the same way as other SQL commands in <application>PL/pgSQL</application>: <application>PL/pgSQL</application> variable names are substituted, and the query plan is cached for possible reuse. When a <application>PL/pgSQL</application> variable is substituted into the cursor query, the value that is substituted is the one it has at the time of the <command>OPEN</command>; subsequent changes to the variable will not affect the cursor's behavior. The <literal>SCROLL</literal> and <literal>NO SCROLL</literal> options have the same meanings as for a bound cursor. カーソル変数は開かれ、実行するよう指定した問い合わせが付与されます。 既に開いたカーソルを開くことはできず、また、バインドされていないカーソル変数として（つまり、単なるrefcursor変数として）宣言されていなければなりません。 この問い合わせはSELECT文であるか、または（EXPLAINのように）何らかの行を返すものでなければなりません。 この問い合わせは、他のPL/pgSQLのSQL文と同様の方法で扱われます。 PL/pgSQLの変数名は置き換えられ、問い合わせ計画は再利用できるようにキャッシュされます。 PL/pgSQL変数がカーソルを使用する問い合わせに代入された時、変数はOPEN時の値となり、その後の変更はカーソルの動きに影響しません。 SCROLLおよびNO SCROLLオプションの意味はバインドされたカーソルと同様です。

An example: 以下に例を示します。

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

OPEN unbound_cursorvar [ [ NO ] SCROLL ] FOR EXECUTE query_string
                                     [ USING expression [, ... ] ];

The cursor variable is opened and given the specified query to execute. The cursor cannot be open already, and it must have been declared as an unbound cursor variable (that is, as a simple <type>refcursor</type> variable). The query is specified as a string expression, in the same way as in the <command>EXECUTE</command> command. As usual, this gives flexibility so the query plan can vary from one run to the next (see <xref linkend="plpgsql-plan-caching"/>), and it also means that variable substitution is not done on the command string. As with <command>EXECUTE</command>, parameter values can be inserted into the dynamic command via <literal>format()</literal> and <literal>USING</literal>. The <literal>SCROLL</literal> and <literal>NO SCROLL</literal> options have the same meanings as for a bound cursor. カーソル変数は開かれ、実行するよう指定した問い合わせが付与されます。 既に開いたカーソルを開くことはできず、また、バインドされていないカーソル変数として（つまり、単なるrefcursor変数として）宣言されていなければなりません。 問い合わせは、EXECUTEコマンドと同じ方法による文字列式として指定されます。 通常と同様に、これにより、次回に実行する際に違った問い合わせを計画できる柔軟性が得られます(41.11.2参照)。 また、変数置換がコマンド文字列上で行われないことも意味します。 EXECUTEと同様にformat()とUSINGを介して動的コマンドにパラメータ値を挿入することができます。 SCROLLおよびNO SCROLLオプションの意味はバインドされたカーソルと同様です。

An example: 以下に例を示します。

OPEN curs1 FOR EXECUTE format('SELECT * FROM %I WHERE col1 = $1',tabname) USING keyvalue;

In this example, the table name is inserted into the query via <function>format()</function>. The comparison value for <literal>col1</literal> is inserted via a <literal>USING</literal> parameter, so it needs no quoting. この例では、テーブル名は問い合わせにformat()で挿入されています。 col1との比較値はUSING経由で埋め込まれますので、引用符を付ける必要がありません。

OPEN bound_cursorvar [ ( [ argument_name := ] argument_value [, ...] ) ];

This form of <command>OPEN</command> is used to open a cursor variable whose query was bound to it when it was declared. The cursor cannot be open already. A list of actual argument value expressions must appear if and only if the cursor was declared to take arguments. These values will be substituted in the query. 宣言時に問い合わせが結び付いたカーソル変数を開くために使用されるOPENの形式です。 既に開いたカーソルを開くことはできません。 実引数の式のリストはカーソルが引数を取るものと宣言された場合にのみ現れます。 これらの値は問い合わせの中で置き換えられます。

The query plan for a bound cursor is always considered cacheable; there is no equivalent of <command>EXECUTE</command> in this case. Notice that <literal>SCROLL</literal> and <literal>NO SCROLL</literal> cannot be specified in <command>OPEN</command>, as the cursor's scrolling behavior was already determined. バインドされたカーソルの問い合わせ計画は常にキャッシュ可能とみなされます。 この場合、EXECUTEと等価なものはありません。 SCROLLおよびNO SCROLLをOPENにおいて指定できないことに注意してください。 カーソル移動の仕様はすでに決まっているからです。

Argument values can be passed using either <firstterm>positional</firstterm> or <firstterm>named</firstterm> notation. In positional notation, all arguments are specified in order. In named notation, each argument's name is specified using <literal>:=</literal> to separate it from the argument expression. Similar to calling functions, described in <xref linkend="sql-syntax-calling-funcs"/>, it is also allowed to mix positional and named notation. 位置的表記または記名的表記を使用して、引数の値を渡すことができます。 位置的表記では、全ての引数が順番に指定されます。 記名的表記では、引数の式と区別するために:=を使用して、各々の引数の名前が指定されます。 4.3に記述した関数呼び出しと同様に、位置的表記と記名的表記を混用できます。

Examples (these use the cursor declaration examples above): 例を示します（ここでは上例のカーソル宣言を使用します）。

OPEN curs2;
OPEN curs3(42);
OPEN curs3(key := 42);

Because variable substitution is done on a bound cursor's query, there are really two ways to pass values into the cursor: either with an explicit argument to <command>OPEN</command>, or implicitly by referencing a <application>PL/pgSQL</application> variable in the query. However, only variables declared before the bound cursor was declared will be substituted into it. In either case the value to be passed is determined at the time of the <command>OPEN</command>. For example, another way to get the same effect as the <literal>curs3</literal> example above is 変数の代入はバインドされたカーソルの問い合わせで行われるため、カーソルへ値を渡す方法が2つあります。 OPENコマンドの明確な引数とするものと、問い合わせにおけるPL/pgSQL変数として暗黙的に参照するものです。 しかし、バインドされたカーソルの宣言より前に宣言した変数だけが代入されます。 どちらの場合も、OPENの実行時に変数値が決まります。 例えば、上例のcurs3と同じ結果を取得する方法を、以下に示します。

DECLARE
    key integer;
    curs4 CURSOR FOR SELECT * FROM tenk1 WHERE unique1 = key;
BEGIN
    key := 42;
    OPEN curs4;

FETCH [ direction { FROM | IN } ] cursor INTO target;

<command>FETCH</command> retrieves the next row (in the indicated direction) from the cursor into a target, which might be a row variable, a record variable, or a comma-separated list of simple variables, just like <command>SELECT INTO</command>. If there is no suitable row, the target is set to NULL(s). As with <command>SELECT INTO</command>, the special variable <literal>FOUND</literal> can be checked to see whether a row was obtained or not. If no row is obtained, the cursor is positioned after the last row or before the first row, depending on the movement direction. FETCHはSELECT INTOと同様に、カーソルから次の行を（指定された方向に）抽出し、対象に格納します。 対象とは、行変数、レコード変数、または単純な変数をカンマで区切ったリストです。 適切な行がない場合、ターゲットはNULLに設定されます。 SELECT INTOの場合と同様、特殊なFOUND変数を検査することで、行が取得できたかどうかを確認できます。 行が取得されない場合、カーソルは移動方向に応じて最後の行の後または最初の行の前に位置します。

The <replaceable>direction</replaceable> clause can be any of the variants allowed in the SQL <xref linkend="sql-fetch"/> command except the ones that can fetch more than one row; namely, it can be direction句は複数行を取り出すことができるコマンドを除き、SQL FETCHで許可されたどのようなコマンドも可能です。 すなわち、以下のものです。 NEXT, PRIOR, FIRST, LAST, ABSOLUTE count, RELATIVE count, <literal>FORWARD</literal>, or FORWARDまたは BACKWARD. Omitting <replaceable>direction</replaceable> is the same as specifying <literal>NEXT</literal>. In the forms using a <replaceable>count</replaceable>, the <replaceable>count</replaceable> can be any integer-valued expression (unlike the SQL <command>FETCH</command> command, which only allows an integer constant). <replaceable>direction</replaceable> values that require moving backward are likely to fail unless the cursor was declared or opened with the <literal>SCROLL</literal> option. direction句の省略は、NEXTの指定と同じです。 countを使う形式では、countはいかなる整数値の式も可能です。(SQL FETCHコマンドとは異なります。あちらは整数定数のみを受け付けます。) SCROLLオプションを用いてカーソルを宣言または開かないと、directionの値による逆方向への移動の要求は失敗します。

<replaceable>cursor</replaceable> must be the name of a <type>refcursor</type> variable that references an open cursor portal. cursor名は、開いているカーソルのポータルを参照するrefcursor変数名でなければなりません。

Examples: 例：

FETCH curs1 INTO rowvar;
FETCH curs2 INTO foo, bar, baz;
FETCH LAST FROM curs3 INTO x, y;
FETCH RELATIVE -2 FROM curs4 INTO x;

MOVE [ direction { FROM | IN } ] cursor;

<command>MOVE</command> repositions a cursor without retrieving any data. <command>MOVE</command> works like the <command>FETCH</command> command, except it only repositions the cursor and does not return the row moved to. The <replaceable>direction</replaceable> clause can be any of the variants allowed in the SQL <xref linkend="sql-fetch"/> command, including those that can fetch more than one row; the cursor is positioned to the last such row. (However, the case in which the <replaceable>direction</replaceable> clause is simply a <replaceable>count</replaceable> expression with no key word is deprecated in <application>PL/pgSQL</application>. That syntax is ambiguous with the case where the <replaceable>direction</replaceable> clause is omitted altogether, and hence it may fail if the <replaceable>count</replaceable> is not a constant.) As with <command>SELECT INTO</command>, the special variable <literal>FOUND</literal> can be checked to see whether there was a row to move to. If there is no such row, the cursor is positioned after the last row or before the first row, depending on the movement direction. MOVEコマンドは、データを取り出さないでカーソルの位置を変更します。 MOVEコマンドは、移動先の行を返さないでカーソルの位置だけを変更することを除けば、FETCHコマンドと同様の働きをします。 direction句は、SQL FETCHコマンドで許可されるどのような形式も可能で、複数行を取り出すことができるものも含まれます。 カーソルはそのような行の最後に位置します。 （しかし、direction句が単にキーワードのないcount式である場合は、PL/pgSQLでは非推奨です。 この構文は、direction句がすべて省略された場合との区別が曖昧であるため、countが定数でない場合は失敗する可能性があります。） SELECT INTOと同様に、特殊な変数FOUNDを用いて、移動先に行が存在するかどうかを検査できます。 そのような行がない場合、カーソルは移動方向に応じて最後の行の後または最初の行の前に位置します。

Examples: 例:

MOVE curs1;
MOVE LAST FROM curs3;
MOVE RELATIVE -2 FROM curs4;
MOVE FORWARD 2 FROM curs4;

UPDATE table SET ... WHERE CURRENT OF cursor;
DELETE FROM table WHERE CURRENT OF cursor;

When a cursor is positioned on a table row, that row can be updated or deleted using the cursor to identify the row. There are restrictions on what the cursor's query can be (in particular, no grouping) and it's best to use <literal>FOR UPDATE</literal> in the cursor. For more information see the <xref linkend="sql-declare"/> reference page. カーソルの位置をテーブルの行に変更すれば、カーソルによって特定した行を更新または消去できます。 カーソル問い合わせは何が許されているのか（特にグループ化しないとき）についての制限があり、それはカーソル内でFOR UPDATEを使用することが最善です。 より詳細についてはDECLAREマニュアルページを参照下さい。

An example: 以下に例を示します。

UPDATE foo SET dataval = myval WHERE CURRENT OF curs1;

CLOSE cursor;

<command>CLOSE</command> closes the portal underlying an open cursor. This can be used to release resources earlier than end of transaction, or to free up the cursor variable to be opened again. CLOSEは、開いているカーソルの背後にあるポータルを閉じます。 これを使用してトランザクションの終わりよりも前にリソースを解放することができ、また、カーソル変数を解放し、再度開くことができます。

An example: 例：

CLOSE curs1;

<application>PL/pgSQL</application> functions can return cursors to the caller. This is useful to return multiple rows or columns, especially with very large result sets. To do this, the function opens the cursor and returns the cursor name to the caller (or simply opens the cursor using a portal name specified by or otherwise known to the caller). The caller can then fetch rows from the cursor. The cursor can be closed by the caller, or it will be closed automatically when the transaction closes. PL/pgSQL関数では、呼び出し元にカーソルを返すことができます。 この方法は、関数から複数行または複数列を返す場合、特にその結果集合が非常に大きい場合に有用です。 これを行うには、関数はカーソルを開き、呼び出し元にカーソル名を返します（もしくは、もし呼び出し元でポータル名がわかっていれば、単純に指定されたポータル名を使用してカーソルを開きます）。 これにより、呼び出し元はカーソルから行を取り出すことができるようになります。 カーソルは呼び出し元で閉じることができます。 または、トランザクションが終了した際に自動的に閉じられます。

The portal name used for a cursor can be specified by the programmer or automatically generated. To specify a portal name, simply assign a string to the <type>refcursor</type> variable before opening it. The string value of the <type>refcursor</type> variable will be used by <command>OPEN</command> as the name of the underlying portal. However, if the <type>refcursor</type> variable's value is null (as it will be by default), then <command>OPEN</command> automatically generates a name that does not conflict with any existing portal, and assigns it to the <type>refcursor</type> variable. カーソル用のポータル名は、プログラマが指定するか、または自動的に生成されます。 ポータル名を指定するには、開く前に、単にrefcursor変数に文字列を代入します。 refcursor変数の文字列値はOPENによって、背後のポータル名として使用されます。 しかし、refcursor変数の値がNULLの場合（デフォルトではそうなっています）、OPENは自動的に既存のポータルと競合しない名前を生成し、それをrefcursor変数に代入します。

The following example shows one way a cursor name can be supplied by the caller: 以下の例は、呼び出し元でカーソル名を指定する方法を示しています。

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;

The following example uses automatic cursor name generation: 以下の例では、自動的に生成されたカーソル名を使用しています。

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


-- need to be in a transaction to use cursors.

-- カーソルを使用するには、トランザクション内部である必要があります。
BEGIN;
SELECT reffunc2();

      reffunc2
--------------------
 <unnamed cursor 1>
(1 row)

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

The following example shows one way to return multiple cursors from a single function: 以下の例は単一関数から複数のカーソルを返す方法を示しています。

CREATE FUNCTION myfunc(refcursor, refcursor) RETURNS SETOF refcursor AS $$
BEGIN
    OPEN $1 FOR SELECT * FROM table_1;
    RETURN NEXT $1;
    OPEN $2 FOR SELECT * FROM table_2;
    RETURN NEXT $2;
END;
$$ LANGUAGE plpgsql;


-- need to be in a transaction to use cursors.

-- カーソルを使用するには、トランザクション内部である必要があります。
BEGIN;

SELECT * FROM myfunc('a', 'b');

FETCH ALL FROM a;
FETCH ALL FROM b;
COMMIT;