FETCH [ direction [ FROM | IN ] ] cursor_name
directionは空にするか、次のいずれかを指定します。
NEXT
PRIOR
FIRST
LAST
ABSOLUTE count
RELATIVE count
count
ALL
FORWARD
FORWARD count
FORWARD ALL
BACKWARD
BACKWARD count
BACKWARD ALL
FETCHは事前に作成されたカーソルを使用して行を取り出します。
カーソルはそれぞれ位置情報を持っており、FETCHはこれを使用します。 カーソル位置として取ることができるのは、問い合わせの結果の先頭行の前、結果内の任意の特定の行、結果の最終行の後のいずれかです。 カーソルの生成時は、カーソル位置は先頭行の前にあります。 行を取り出した後は、カーソル位置は最後に取り出した行にあります。 FETCHが利用可能な行の終わりまで達すると、カーソル位置は最終行の後にあります(後方抽出の場合は先頭行の前になります)。 FETCH ALLもしくはFETCH BACKWARD ALLでは、カーソルの位置は常に最終行の後か、先頭行の前になります。
NEXT、PRIOR、FIRST、LAST、ABSOLUTE、RELATIVE形式では、カーソルを適切に移動した後、行を1つ取り出します。 行が存在しない場合、空の結果が返され、カーソル位置はそのまま先頭行の前か最終行の後に留まります。
FORWARDおよびBACKWARDを使用した構文では、指定数の行を前方もしくは後方方向に取り出します。この時、最後に取り出した行がカーソル位置となります (countが利用可能な行数を超えた場合は、全行の後/前になります)。
RELATIVE 0、FORWARD 0、およびBACKWARD 0は全て、カーソルを移動することなく現在の行を取り出します。 つまり、一番最後に取り出した行を再度取り出すことになります。 カーソルが先頭行の前や最終行の後になければ、これらのコマンドは成功します。 先頭行の前や最終行の後にあれば、行は返されません。
注意: このマニュアルページではSQLコマンドレベルでのカーソルの使用方法について説明します。 PL/pgSQL内でカーソルを使用するつもりであれば、規則が異なりますので、項39.7を参照してください。
directionは、取り出す方向と取り出す行数を定義します。 以下のいずれかを指定できます。
次の行を取り出します。 これは、directionが省略された時のデフォルトです。
1つ前の行を取り出します。
問い合わせの先頭行を取り出します (ABSOLUTE 1と同じです)。
問い合わせの最終行を取り出します (ABSOLUTE -1と同じです)。
問い合わせのcount番目の行を取り出します。 countが負ならば、終わりからabs(count)番目の行を取り出します。 countが範囲外の場合、カーソル位置は先頭行の前か最終行の後になります。 特に、ABSOLUTE 0と指定すると、先頭行の前になります。
カーソルの現在位置からcount番目の行を取り出します。 countが負の場合、現在位置よりabs(count)行分前の行を取り出します。 RELATIVE 0と指定すると、現在の行があれば、その行を再度取り出します。
次のcount行を取り出します (FORWARD countと同じです)。
残っている行を全て取り出します (FORWARD ALLと同じです)。
1つ次の行を取り出します (NEXTと同じです)。
次のcount行分の行を取り出します。 FORWARD 0と指定すると、現在の行を再度取り出します。
残っている行を全て取り出します。
1つ前の行を取り出します (PRIORと同じです)。
前のcount行分の行を(逆方向に走査して)取り出します。 BACKWARD 0と指定すると、現在の行を再度取り出します。
現在位置より前の行を(逆方向に走査して)全て取り出します。
取り出す位置や行数を決定するcountは、整数定数で、符号を付けることができます。 FORWARDとBACKWARDにおいて、countに負の値を指定すると、FORWARDとBACKWARDの意味が入れ替わると考えることができます。
開いているカーソルの名前を指定します。
正常に終了すると、FETCHコマンドは以下の形式のコマンドタグを返します。
FETCH count
countは取り出した行数です(0の可能性もあります)。 psqlでは取り出した行数を別途表示するため、このコマンドタグは実際には表示されないことに注意してください。
FETCHコマンドとして、FETCH NEXTもしくはFETCH FORWARD以外を使用する場合、カーソルをSCROLLオプション付きで宣言しなければなりません。 単純な問い合わせでは、PostgreSQLにより、カーソルがSCROLL付きで宣言されていなくても後方向の取り出しを行うことができますが、この動作に依存すべきではありません。 カーソルがNO SCROLL付きで宣言された場合は、後方向の取り出しを行うことができません。
相対的な指定による指定行への移動に比べると、ABSOLUTEによる取り出しは高速ではありません。 内部的な実装では、必ず中間の行を全て経由しているからです。 絶対指定で負の値を指定した場合、速度はさらに悪化します。 まず、最終行を見つけるために最後まで問い合わせを読み取って、その後に最終行から後方に移動するためです。 ただし、(FETCH ABSOLUTE 0を使用して)問い合わせの先頭へ戻る時は高速です。
DECLAREを使用してカーソルを定義します。 データを取り出さずにカーソル位置を変更する場合はMOVEを使用してください。
次の例では、カーソルを使用してテーブル内を行き来しています。
BEGIN WORK; -- カーソルを設定します。 DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films; -- liahonaカーソルから最初の5行を取り出します。 FETCH FORWARD 5 FROM liahona; code | title | did | date_prod | kind | len -------+-------------------------+-----+------------+----------+------- BL101 | The Third Man | 101 | 1949-12-23 | Drama | 01:44 BL102 | The African Queen | 101 | 1951-08-11 | Romantic | 01:43 JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25 P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 P_302 | Becket | 103 | 1964-02-03 | Drama | 02:28 -- 1つ前の行を取り出します。 FETCH PRIOR FROM liahona; code | title | did | date_prod | kind | len -------+---------+-----+------------+--------+------- P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08 -- カーソルを閉じ、トランザクションを終了します。 CLOSE liahona; COMMIT WORK;