.\\" auto-generated by docbook2man-spec $Revision: 1.2 $
.TH "FETCH" "" "2007-05-04" "SQL - 言語" "SQLコマンド"
.SH NAME
FETCH \- カーソルを使用してテーブルから行を抽出する

.SH SYNOPSIS
.sp
.nf
FETCH [ \fIdirection\fR { FROM | IN } ] \fIcursorname\fR

\fIdirection\fRは空にするか、次のいずれかを指定します。
    NEXT
    PRIOR
    FIRST
    LAST
    ABSOLUTE \fIcount\fR
    RELATIVE \fIcount\fR
    \fIcount\fR
    ALL
    FORWARD
    FORWARD \fIcount\fR
    FORWARD ALL
    BACKWARD
    BACKWARD \fIcount\fR
    BACKWARD ALL
.sp
.fi
.SH "説明"
.PP
\fBFETCH\fRは事前に作成されたカーソルを使用して行を取り出します。
.PP
カーソルはそれぞれ位置情報を持っており、\fBFETCH\fRはこれを使用します。
カーソル位置として取ることができるのは、問い合わせの結果の先頭行の前、結果内の任意の特定の行、結果の最終行の後のいずれかです。
カーソルの生成時は、カーソル位置は先頭行の前にあります。
行を取り出した後は、カーソル位置は最後に取り出した行にあります。
\fBFETCH\fRが利用可能な行の終わりまで達すると、カーソル位置は最終行の後にあります（後方抽出の場合は先頭行の前になります）。
\fBFETCH ALL\fRもしくは\fBFETCH BACKWARD ALL\fRでは、カーソルの位置は常に最終行の後か、先頭行の前になります。
.PP
NEXT、PRIOR、FIRST、LAST、ABSOLUTE、RELATIVE形式では、カーソルを適切に移動した後、行を1つ取り出します。
行が存在しない場合、空の結果が返され、カーソル位置はそのまま先頭行の前か最終行の後に留まります。
.PP
FORWARDおよびBACKWARDを使用した構文では、指定数の行を前方もしくは後方方向に取り出します。この時、最後に取り出した行がカーソル位置となります
（\fIcount\fRが利用可能な行数を超えた場合は、全行の後/前になります）。
.PP
RELATIVE 0、FORWARD 0、およびBACKWARD 0は全て、カーソルを移動することなく現在の行を取り出します。
つまり、一番最後に取り出した行を再度取り出すことになります。
カーソルが先頭行の前や最終行の後になければ、これらのコマンドは成功します。
先頭行の前や最終行の後にあれば、行は返されません。
.SH "パラメータ"
.TP
\fB\fIdirection\fB\fR
\fIdirection\fRは、取り出す方向と取り出す行数を定義します。
以下のいずれかを指定できます。
.RS
.TP
\fBNEXT\fR
次の行を取り出します。
これは、\fIdirection\fRが省略された時のデフォルトです。
.TP
\fBPRIOR\fR
1つ前の行を取り出します。
.TP
\fBFIRST\fR
問い合わせの先頭行を取り出します
（ABSOLUTE 1と同じです）。
.TP
\fBLAST\fR
問い合わせの最終行を取り出します
（ABSOLUTE -1と同じです）。
.TP
\fBABSOLUTE \fIcount\fB\fR
問い合わせの\fIcount\fR番目の行を取り出します。
\fIcount\fRが負ならば、終わりからabs(\fIcount\fR)番目の行を取り出します。
\fIcount\fRが範囲外の場合、カーソル位置は先頭行の前か最終行の後になります。
特に、ABSOLUTE 0と指定すると、先頭行の前になります。
.TP
\fBRELATIVE \fIcount\fB\fR
カーソルの現在位置から\fIcount\fR番目の行を取り出します。
\fIcount\fRが負の場合、現在位置よりabs(\fIcount\fR)行分前の行を取り出します。
RELATIVE 0と指定すると、現在の行があれば、その行を再度取り出します。
.TP
\fB\fIcount\fB\fR
次の\fIcount\fR行を取り出します
（FORWARD \fIcount\fRと同じです）。
.TP
\fBALL\fR
残っている行を全て取り出します
（FORWARD ALLと同じです）。
.TP
\fBFORWARD\fR
1つ次の行を取り出します
（NEXTと同じです）。
.TP
\fBFORWARD \fIcount\fB\fR
次の\fIcount\fR行分の行を取り出します。
FORWARD 0と指定すると、現在の行を再度取り出します。
.TP
\fBFORWARD ALL\fR
残っている行を全て取り出します。
.TP
\fBBACKWARD\fR
1つ前の行を取り出します
（PRIORと同じです）。
.TP
\fBBACKWARD \fIcount\fB\fR
前の\fIcount\fR行分の行を（逆方向に走査して）取り出します。
BACKWARD 0と指定すると、現在の行を再度取り出します。
.TP
\fBBACKWARD ALL\fR
現在位置より前の行を（逆方向に走査して）全て取り出します。
.RE
.PP
.TP
\fB\fIcount\fB\fR
取り出す位置や行数を決定する\fIcount\fRは、整数定数で、符号を付けることができます。
FORWARDとBACKWARDにおいて、\fIcount\fRに負の値を指定すると、FORWARDとBACKWARDの意味が入れ替わると考えることができます。
.TP
\fB\fIcursorname\fB\fR
開いているカーソルの名前を指定します。
.SH "出力"
.PP
正常に終了すると、\fBFETCH\fRコマンドは以下の形式のコマンドタグを返します。
.sp
.nf
FETCH \fIcount\fR
.sp
.fi
\fIcount\fRは取り出した行数です（0の可能性もあります）。
\fBpsql\fRでは取り出した行数を別途表示するため、このコマンドタグは実際には表示されないことに注意してください。
.SH "注釈"
.PP
\fBFETCH\fRコマンドとして、\fBFETCH NEXT\fRもしくは\fBFETCH FORWARD\fR以外を使用する場合、カーソルをSCROLLオプション付きで宣言しなければなりません。
単純な問い合わせでは、PostgreSQLにより、カーソルがSCROLL付きで宣言されていなくても後方向の取り出しを行うことができますが、この動作に依存すべきではありません。
カーソルがNO SCROLL付きで宣言された場合は、後方向の取り出しを行うことができません。
.PP
相対的な指定による指定行への移動に比べると、ABSOLUTEによる取り出しは高速ではありません。
内部的な実装では、必ず中間の行を全て経由しているからです。
絶対指定で負の値を指定した場合、速度はさらに悪化します。
まず、最終行を見つけるために最後まで問い合わせを読み取って、その後に最終行から後方に移動するためです。
ただし、（FETCH ABSOLUTE 0を使用して）問い合わせの先頭へ戻る時は高速です。
.PP
現在、PostgreSQLでは、カーソルを使用したデータの更新をサポートしていません。
.PP
DECLARE [\fBdeclare\fR(l)]を使用してカーソルを定義します。
データを取り出さずにカーソル位置を変更する場合はMOVE [\fBmove\fR(l)]を使用してください。
.SH "例"
.PP
次の例では、カーソルを使用してテーブル内を行き来しています。
.sp
.nf
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;
.sp
.fi
.SH "互換性"
.PP
標準SQLでは、埋め込みSQLにおける\fBFETCH\fRのみが定義されています。
上記で説明した各種の\fBFETCH\fRは、ホスト変数への代入ではなく、\fBSELECT\fRの結果であるかのようにデータを返します。
この点を除き、\fBFETCH\fRは完全に標準SQLと上位互換性を持ちます。
.PP
FORWARDとBACKWARDを持つ\fBFETCH\fRの形式や、暗黙的なFORWARDを持つFETCH \fIcount\fRとFETCH ALLはPostgreSQLの拡張です。
.PP
標準SQLでは、カーソル名の前に付けられるのはFROMのみです。
INを使用するオプションはPostgreSQLの拡張です。
.SH "関連項目"
CLOSE [\fBclose\fR(l)], DECLARE [\fBdeclare\fR(l)], MOVE [\fBmove\fR(l)]
