FETCH(7)

NAME
FETCH - カーソルを使用してテーブルから行を抽出する

SYNOPSIS

FETCH [ direction { FROM | IN } ] cursorname
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は全て、カーソルを移動することなく現在の行を取り出します。 つまり、一番最後に取り出した行を再度取り出すことになります。 カーソルが先頭行の前や最終行の後になければ、これらのコマンドは成功します。 先頭行の前や最終行の後にあれば、行は返されません。

    Note: このマニュアルページではSQLコマンドレベルでのカーソルの使用方法について説明します。 PL/pgSQL内でカーソルを使用するつもりであれば、規則が異なりますので、in the documentationを参照してください。

パラメータ

direction
    directionは、取り出す方向と取り出す行数を定義します。 以下のいずれかを指定できます。

    NEXT
        次の行を取り出します。 これは、directionが省略された時のデフォルトです。

    PRIOR
        1つ前の行を取り出します。

    FIRST
        問い合わせの先頭行を取り出します （ABSOLUTE 1と同じです）。

    LAST
        問い合わせの最終行を取り出します （ABSOLUTE -1と同じです）。

    ABSOLUTE count
        問い合わせのcount番目の行を取り出します。 countが負ならば、終わりからabs(count)番目の行を取り出します。 countが範囲外の場合、カーソル位置は先頭行の前か最終行の後になります。 特に、ABSOLUTE 0と指定すると、先頭行の前になります。

    RELATIVE count
        カーソルの現在位置からcount番目の行を取り出します。 countが負の場合、現在位置よりabs(count)行分前の行を取り出します。 RELATIVE 0と指定すると、現在の行があれば、その行を再度取り出します。

    count
        次のcount行を取り出します （FORWARD countと同じです）。

    ALL 残っている行を全て取り出します （FORWARD ALLと同じです）。

    FORWARD
        1つ次の行を取り出します （NEXTと同じです）。

    FORWARD count
        次のcount行分の行を取り出します。 FORWARD 0と指定すると、現在の行を再度取り出します。

    FORWARD ALL
        残っている行を全て取り出します。

    BACKWARD
        1つ前の行を取り出します （PRIORと同じです）。

    BACKWARD count
        前のcount行分の行を（逆方向に走査して）取り出します。 BACKWARD 0と指定すると、現在の行を再度取り出します。

    BACKWARD ALL
        現在位置より前の行を（逆方向に走査して）全て取り出します。

count
    取り出す位置や行数を決定するcountは、整数定数で、符号を付けることができます。 FORWARDとBACKWARDにおいて、countに負の値を指定すると、FORWARDとBACKWARDの意味が入れ替わると考えることができます。

cursorname
    開いているカーソルの名前を指定します。

出力

正常に終了すると、FETCHコマンドは以下の形式のコマンドタグを返します。

FETCH count

countは取り出した行数です（0の可能性もあります）。 psqlでは取り出した行数を別途表示するため、このコマンドタグは実際には表示されないことに注意してください。

注釈

FETCHコマンドとして、FETCH NEXTもしくはFETCH FORWARD以外を使用する場合、カーソルをSCROLLオプション付きで宣言しなければなりません。 単純な問い合わせでは、PostgreSQLにより、カーソルがSCROLL付きで宣言されていなくても後方向の取り出しを行うことができますが、この動作に依存すべきではありません。 カーソルがNO SCROLL付きで宣言された場合は、後方向の取り出しを行うことができません。

相対的な指定による指定行への移動に比べると、ABSOLUTEによる取り出しは高速ではありません。 内部的な実装では、必ず中間の行を全て経由しているからです。 絶対指定で負の値を指定した場合、速度はさらに悪化します。 まず、最終行を見つけるために最後まで問い合わせを読み取って、その後に最終行から後方に移動するためです。 ただし、（FETCH ABSOLUTE 0を使用して）問い合わせの先頭へ戻る時は高速です。

DECLARE [declare(7)]を使用してカーソルを定義します。 データを取り出さずにカーソル位置を変更する場合はMOVE [move(7)]を使用してください。

例

次の例では、カーソルを使用してテーブル内を行き来しています。

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;

互換性

標準SQLでは、埋め込みSQLにおけるFETCHのみが定義されています。 上記で説明した各種のFETCHは、ホスト変数への代入ではなく、SELECTの結果であるかのようにデータを返します。 この点を除き、FETCHは完全に標準SQLと上位互換性を持ちます。

FORWARDとBACKWARDを持つFETCHの形式や、暗黙的なFORWARDを持つFETCH countとFETCH ALLはPostgreSQLの拡張です。

標準SQLでは、カーソル名の前に付けられるのはFROMのみです。 INを使用するオプションはPostgreSQLの拡張です。

関連項目
CLOSE [close(7)], DECLARE [declare(7)], MOVE [move(7)]