begriffs open source - ai-pg/blob - full-docs/man7/FETCH.7

   1 '\" t
   2 .\"     Title: FETCH
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "FETCH" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 FETCH \- retrieve rows from a query using a cursor
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 FETCH [ \fIdirection\fR ] [ FROM | IN ] \fIcursor_name\fR
  36
  37 where \fIdirection\fR can be one of:
  38
  39     NEXT
  40     PRIOR
  41     FIRST
  42     LAST
  43     ABSOLUTE \fIcount\fR
  44     RELATIVE \fIcount\fR
  45     \fIcount\fR
  46     ALL
  47     FORWARD
  48     FORWARD \fIcount\fR
  49     FORWARD ALL
  50     BACKWARD
  51     BACKWARD \fIcount\fR
  52     BACKWARD ALL
  53 .fi
  54 .SH "DESCRIPTION"
  55 .PP
  56 \fBFETCH\fR
  57 retrieves rows using a previously\-created cursor\&.
  58 .PP
  59 A cursor has an associated position, which is used by
  60 \fBFETCH\fR\&. The cursor position can be before the first row of the query result, on any particular row of the result, or after the last row of the result\&. When created, a cursor is positioned before the first row\&. After fetching some rows, the cursor is positioned on the row most recently retrieved\&. If
  61 \fBFETCH\fR
  62 runs off the end of the available rows then the cursor is left positioned after the last row, or before the first row if fetching backward\&.
  63 \fBFETCH ALL\fR
  64 or
  65 \fBFETCH BACKWARD ALL\fR
  66 will always leave the cursor positioned after the last row or before the first row\&.
  67 .PP
  68 The forms
  69 NEXT,
  70 PRIOR,
  71 FIRST,
  72 LAST,
  73 ABSOLUTE,
  74 RELATIVE
  75 fetch a single row after moving the cursor appropriately\&. If there is no such row, an empty result is returned, and the cursor is left positioned before the first row or after the last row as appropriate\&.
  76 .PP
  77 The forms using
  78 FORWARD
  79 and
  80 BACKWARD
  81 retrieve the indicated number of rows moving in the forward or backward direction, leaving the cursor positioned on the last\-returned row (or after/before all rows, if the
  82 \fIcount\fR
  83 exceeds the number of rows available)\&.
  84 .PP
  85 RELATIVE 0,
  86 FORWARD 0, and
  87 BACKWARD 0
  88 all request fetching the current row without moving the cursor, that is, re\-fetching the most recently fetched row\&. This will succeed unless the cursor is positioned before the first row or after the last row; in which case, no row is returned\&.
  89 .if n \{\
  90 .sp
  91 .\}
  92 .RS 4
  93 .it 1 an-trap
  94 .nr an-no-space-flag 1
  95 .nr an-break-flag 1
  96 .br
  97 .ps +1
  98 \fBNote\fR
  99 .ps -1
 100 .br
 101 .PP
 102 This page describes usage of cursors at the SQL command level\&. If you are trying to use cursors inside a
 103 PL/pgSQL
 104 function, the rules are different \(em see
 105 Section\ \&41.7.3\&.
 106 .sp .5v
 107 .RE
 108 .SH "PARAMETERS"
 109 .PP
 110 \fIdirection\fR
 111 .RS 4
 112 \fIdirection\fR
 113 defines the fetch direction and number of rows to fetch\&. It can be one of the following:
 114 .PP
 115 NEXT
 116 .RS 4
 117 Fetch the next row\&. This is the default if
 118 \fIdirection\fR
 119 is omitted\&.
 120 .RE
 121 .PP
 122 PRIOR
 123 .RS 4
 124 Fetch the prior row\&.
 125 .RE
 126 .PP
 127 FIRST
 128 .RS 4
 129 Fetch the first row of the query (same as
 130 ABSOLUTE 1)\&.
 131 .RE
 132 .PP
 133 LAST
 134 .RS 4
 135 Fetch the last row of the query (same as
 136 ABSOLUTE \-1)\&.
 137 .RE
 138 .PP
 139 ABSOLUTE \fIcount\fR
 140 .RS 4
 141 Fetch the
 142 \fIcount\fR\*(Aqth row of the query, or the
 143 abs(\fIcount\fR)\*(Aqth row from the end if
 144 \fIcount\fR
 145 is negative\&. Position before first row or after last row if
 146 \fIcount\fR
 147 is out of range; in particular,
 148 ABSOLUTE 0
 149 positions before the first row\&.
 150 .RE
 151 .PP
 152 RELATIVE \fIcount\fR
 153 .RS 4
 154 Fetch the
 155 \fIcount\fR\*(Aqth succeeding row, or the
 156 abs(\fIcount\fR)\*(Aqth prior row if
 157 \fIcount\fR
 158 is negative\&.
 159 RELATIVE 0
 160 re\-fetches the current row, if any\&.
 161 .RE
 162 .PP
 163 \fIcount\fR
 164 .RS 4
 165 Fetch the next
 166 \fIcount\fR
 167 rows (same as
 168 FORWARD \fIcount\fR)\&.
 169 .RE
 170 .PP
 171 ALL
 172 .RS 4
 173 Fetch all remaining rows (same as
 174 FORWARD ALL)\&.
 175 .RE
 176 .PP
 177 FORWARD
 178 .RS 4
 179 Fetch the next row (same as
 180 NEXT)\&.
 181 .RE
 182 .PP
 183 FORWARD \fIcount\fR
 184 .RS 4
 185 Fetch the next
 186 \fIcount\fR
 187 rows\&.
 188 FORWARD 0
 189 re\-fetches the current row\&.
 190 .RE
 191 .PP
 192 FORWARD ALL
 193 .RS 4
 194 Fetch all remaining rows\&.
 195 .RE
 196 .PP
 197 BACKWARD
 198 .RS 4
 199 Fetch the prior row (same as
 200 PRIOR)\&.
 201 .RE
 202 .PP
 203 BACKWARD \fIcount\fR
 204 .RS 4
 205 Fetch the prior
 206 \fIcount\fR
 207 rows (scanning backwards)\&.
 208 BACKWARD 0
 209 re\-fetches the current row\&.
 210 .RE
 211 .PP
 212 BACKWARD ALL
 213 .RS 4
 214 Fetch all prior rows (scanning backwards)\&.
 215 .RE
 216 .RE
 217 .PP
 218 \fIcount\fR
 219 .RS 4
 220 \fIcount\fR
 221 is a possibly\-signed integer constant, determining the location or number of rows to fetch\&. For
 222 FORWARD
 223 and
 224 BACKWARD
 225 cases, specifying a negative
 226 \fIcount\fR
 227 is equivalent to changing the sense of
 228 FORWARD
 229 and
 230 BACKWARD\&.
 231 .RE
 232 .PP
 233 \fIcursor_name\fR
 234 .RS 4
 235 An open cursor\*(Aqs name\&.
 236 .RE
 237 .SH "OUTPUTS"
 238 .PP
 239 On successful completion, a
 240 \fBFETCH\fR
 241 command returns a command tag of the form
 242 .sp
 243 .if n \{\
 244 .RS 4
 245 .\}
 246 .nf
 247 FETCH \fIcount\fR
 248 .fi
 249 .if n \{\
 250 .RE
 251 .\}
 252 .sp
 253 The
 254 \fIcount\fR
 255 is the number of rows fetched (possibly zero)\&. Note that in
 256 psql, the command tag will not actually be displayed, since
 257 psql
 258 displays the fetched rows instead\&.
 259 .SH "NOTES"
 260 .PP
 261 The cursor should be declared with the
 262 SCROLL
 263 option if one intends to use any variants of
 264 \fBFETCH\fR
 265 other than
 266 \fBFETCH NEXT\fR
 267 or
 268 \fBFETCH FORWARD\fR
 269 with a positive count\&. For simple queries
 270 PostgreSQL
 271 will allow backwards fetch from cursors not declared with
 272 SCROLL, but this behavior is best not relied on\&. If the cursor is declared with
 273 NO SCROLL, no backward fetches are allowed\&.
 274 .PP
 275 ABSOLUTE
 276 fetches are not any faster than navigating to the desired row with a relative move: the underlying implementation must traverse all the intermediate rows anyway\&. Negative absolute fetches are even worse: the query must be read to the end to find the last row, and then traversed backward from there\&. However, rewinding to the start of the query (as with
 277 FETCH ABSOLUTE 0) is fast\&.
 278 .PP
 279 \fBDECLARE\fR
 280 is used to define a cursor\&. Use
 281 \fBMOVE\fR
 282 to change cursor position without retrieving data\&.
 283 .SH "EXAMPLES"
 284 .PP
 285 The following example traverses a table using a cursor:
 286 .sp
 287 .if n \{\
 288 .RS 4
 289 .\}
 290 .nf
 291 BEGIN WORK;
 292
 293 \-\- Set up a cursor:
 294 DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;
 295
 296 \-\- Fetch the first 5 rows in the cursor liahona:
 297 FETCH FORWARD 5 FROM liahona;
 298
 299  code  |          title          | did | date_prod  |   kind   |  len
 300 \-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-
 301  BL101 | The Third Man           | 101 | 1949\-12\-23 | Drama    | 01:44
 302  BL102 | The African Queen       | 101 | 1951\-08\-11 | Romantic | 01:43
 303  JL201 | Une Femme est une Femme | 102 | 1961\-03\-12 | Romantic | 01:25
 304  P_301 | Vertigo                 | 103 | 1958\-11\-14 | Action   | 02:08
 305  P_302 | Becket                  | 103 | 1964\-02\-03 | Drama    | 02:28
 306
 307 \-\- Fetch the previous row:
 308 FETCH PRIOR FROM liahona;
 309
 310  code  |  title  | did | date_prod  |  kind  |  len
 311 \-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-+\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-
 312  P_301 | Vertigo | 103 | 1958\-11\-14 | Action | 02:08
 313
 314 \-\- Close the cursor and end the transaction:
 315 CLOSE liahona;
 316 COMMIT WORK;
 317 .fi
 318 .if n \{\
 319 .RE
 320 .\}
 321 .SH "COMPATIBILITY"
 322 .PP
 323 The SQL standard defines
 324 \fBFETCH\fR
 325 for use in embedded SQL only\&. The variant of
 326 \fBFETCH\fR
 327 described here returns the data as if it were a
 328 \fBSELECT\fR
 329 result rather than placing it in host variables\&. Other than this point,
 330 \fBFETCH\fR
 331 is fully upward\-compatible with the SQL standard\&.
 332 .PP
 333 The
 334 \fBFETCH\fR
 335 forms involving
 336 FORWARD
 337 and
 338 BACKWARD, as well as the forms
 339 FETCH \fIcount\fR
 340 and
 341 FETCH ALL, in which
 342 FORWARD
 343 is implicit, are
 344 PostgreSQL
 345 extensions\&.
 346 .PP
 347 The SQL standard allows only
 348 FROM
 349 preceding the cursor name; the option to use
 350 IN, or to leave them out altogether, is an extension\&.
 351 .SH "SEE ALSO"
 352 \fBCLOSE\fR(7), \fBDECLARE\fR(7), \fBMOVE\fR(7)