PostgreSQL 9.1.1文書
前のページ | 巻戻し |  | 早送り | 次のページ

# FETCH

## 名前

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

## 概要

    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`は、取り出す方向と取り出す行数を定義します。 以下のいずれかを指定できます。

  `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`の意味が入れ替わると考えることができます。

`cursor_name`

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

## 出力

正常に終了すると、`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;

## 互換性

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

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

標準SQLでは、カーソル名の前に付けられるのは`FROM`のみです。 `IN`を使用するオプション、または、どちらも省略することはPostgreSQLの拡張です。

## 関連項目

CLOSE, DECLARE, MOVE

前のページ | ホーム | 次のページ
EXPLAIN | 上に戻る | GRANT