begriffs open source - ai-pg/blob - full-docs/txt/sql-fetch.txt

   1
   2 FETCH
   3
   4    FETCH — retrieve rows from a query using a cursor
   5
   6 Synopsis
   7
   8 FETCH [ direction ] [ FROM | IN ] cursor_name
   9
  10 where direction can be one of:
  11
  12     NEXT
  13     PRIOR
  14     FIRST
  15     LAST
  16     ABSOLUTE count
  17     RELATIVE count
  18     count
  19     ALL
  20     FORWARD
  21     FORWARD count
  22     FORWARD ALL
  23     BACKWARD
  24     BACKWARD count
  25     BACKWARD ALL
  26
  27 Description
  28
  29    FETCH retrieves rows using a previously-created cursor.
  30
  31    A cursor has an associated position, which is used by FETCH. The cursor
  32    position can be before the first row of the query result, on any
  33    particular row of the result, or after the last row of the result. When
  34    created, a cursor is positioned before the first row. After fetching
  35    some rows, the cursor is positioned on the row most recently retrieved.
  36    If FETCH runs off the end of the available rows then the cursor is left
  37    positioned after the last row, or before the first row if fetching
  38    backward. FETCH ALL or FETCH BACKWARD ALL will always leave the cursor
  39    positioned after the last row or before the first row.
  40
  41    The forms NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE fetch a single
  42    row after moving the cursor appropriately. If there is no such row, an
  43    empty result is returned, and the cursor is left positioned before the
  44    first row or after the last row as appropriate.
  45
  46    The forms using FORWARD and BACKWARD retrieve the indicated number of
  47    rows moving in the forward or backward direction, leaving the cursor
  48    positioned on the last-returned row (or after/before all rows, if the
  49    count exceeds the number of rows available).
  50
  51    RELATIVE 0, FORWARD 0, and BACKWARD 0 all request fetching the current
  52    row without moving the cursor, that is, re-fetching the most recently
  53    fetched row. This will succeed unless the cursor is positioned before
  54    the first row or after the last row; in which case, no row is returned.
  55
  56 Note
  57
  58    This page describes usage of cursors at the SQL command level. If you
  59    are trying to use cursors inside a PL/pgSQL function, the rules are
  60    different — see Section 41.7.3.
  61
  62 Parameters
  63
  64    direction
  65           direction defines the fetch direction and number of rows to
  66           fetch. It can be one of the following:
  67
  68         NEXT
  69                 Fetch the next row. This is the default if direction is
  70                 omitted.
  71
  72         PRIOR
  73                 Fetch the prior row.
  74
  75         FIRST
  76                 Fetch the first row of the query (same as ABSOLUTE 1).
  77
  78         LAST
  79                 Fetch the last row of the query (same as ABSOLUTE -1).
  80
  81         ABSOLUTE count
  82                 Fetch the count'th row of the query, or the abs(count)'th
  83                 row from the end if count is negative. Position before
  84                 first row or after last row if count is out of range; in
  85                 particular, ABSOLUTE 0 positions before the first row.
  86
  87         RELATIVE count
  88                 Fetch the count'th succeeding row, or the abs(count)'th
  89                 prior row if count is negative. RELATIVE 0 re-fetches the
  90                 current row, if any.
  91
  92         count
  93                 Fetch the next count rows (same as FORWARD count).
  94
  95         ALL
  96                 Fetch all remaining rows (same as FORWARD ALL).
  97
  98         FORWARD
  99                 Fetch the next row (same as NEXT).
 100
 101         FORWARD count
 102                 Fetch the next count rows. FORWARD 0 re-fetches the
 103                 current row.
 104
 105         FORWARD ALL
 106                 Fetch all remaining rows.
 107
 108         BACKWARD
 109                 Fetch the prior row (same as PRIOR).
 110
 111         BACKWARD count
 112                 Fetch the prior count rows (scanning backwards). BACKWARD
 113                 0 re-fetches the current row.
 114
 115         BACKWARD ALL
 116                 Fetch all prior rows (scanning backwards).
 117
 118    count
 119           count is a possibly-signed integer constant, determining the
 120           location or number of rows to fetch. For FORWARD and BACKWARD
 121           cases, specifying a negative count is equivalent to changing the
 122           sense of FORWARD and BACKWARD.
 123
 124    cursor_name
 125           An open cursor's name.
 126
 127 Outputs
 128
 129    On successful completion, a FETCH command returns a command tag of the
 130    form
 131 FETCH count
 132
 133    The count is the number of rows fetched (possibly zero). Note that in
 134    psql, the command tag will not actually be displayed, since psql
 135    displays the fetched rows instead.
 136
 137 Notes
 138
 139    The cursor should be declared with the SCROLL option if one intends to
 140    use any variants of FETCH other than FETCH NEXT or FETCH FORWARD with a
 141    positive count. For simple queries PostgreSQL will allow backwards
 142    fetch from cursors not declared with SCROLL, but this behavior is best
 143    not relied on. If the cursor is declared with NO SCROLL, no backward
 144    fetches are allowed.
 145
 146    ABSOLUTE fetches are not any faster than navigating to the desired row
 147    with a relative move: the underlying implementation must traverse all
 148    the intermediate rows anyway. Negative absolute fetches are even worse:
 149    the query must be read to the end to find the last row, and then
 150    traversed backward from there. However, rewinding to the start of the
 151    query (as with FETCH ABSOLUTE 0) is fast.
 152
 153    DECLARE is used to define a cursor. Use MOVE to change cursor position
 154    without retrieving data.
 155
 156 Examples
 157
 158    The following example traverses a table using a cursor:
 159 BEGIN WORK;
 160
 161 -- Set up a cursor:
 162 DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;
 163
 164 -- Fetch the first 5 rows in the cursor liahona:
 165 FETCH FORWARD 5 FROM liahona;
 166
 167  code  |          title          | did | date_prod  |   kind   |  len
 168 -------+-------------------------+-----+------------+----------+-------
 169  BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
 170  BL102 | The African Queen       | 101 | 1951-08-11 | Romantic | 01:43
 171  JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
 172  P_301 | Vertigo                 | 103 | 1958-11-14 | Action   | 02:08
 173  P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28
 174
 175 -- Fetch the previous row:
 176 FETCH PRIOR FROM liahona;
 177
 178  code  |  title  | did | date_prod  |  kind  |  len
 179 -------+---------+-----+------------+--------+-------
 180  P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
 181
 182 -- Close the cursor and end the transaction:
 183 CLOSE liahona;
 184 COMMIT WORK;
 185
 186 Compatibility
 187
 188    The SQL standard defines FETCH for use in embedded SQL only. The
 189    variant of FETCH described here returns the data as if it were a SELECT
 190    result rather than placing it in host variables. Other than this point,
 191    FETCH is fully upward-compatible with the SQL standard.
 192
 193    The FETCH forms involving FORWARD and BACKWARD, as well as the forms
 194    FETCH count and FETCH ALL, in which FORWARD is implicit, are PostgreSQL
 195    extensions.
 196
 197    The SQL standard allows only FROM preceding the cursor name; the option
 198    to use IN, or to leave them out altogether, is an extension.
 199
 200 See Also
 201
 202    CLOSE, DECLARE, MOVE