Retrieves rows from a cursor.
FETCH direction [ count ] { IN | FROM } cursor direction ::= { FORWARD | BACKWARD | RELATIVE } count ::= { numrows | ALL | NEXT | PRIOR }
direction
Use the optional direction
parameter to
specify the direction you want to fetch. It may be specified as any of the following
keywords:
FORWARD
The keyword used to retrieve rows following the current position. This is the
default, if the direction
is not explicitly
set.
BACKWARD
The keyword used to retrieve rows preceding the current position.
RELATIVE
A noise term made available for SQL92 compatibility. As of PostgreSQL 7.1.x, all
cursors locate rows relative to the current cursor position, and this keyword therefore
has no effect. Note that combining the RELATIVE
keyword with a
count
of 0 will produce an error (see the “Results” section later
in this reference entry).
count
This parameter takes the number of rows you wish to fetch. You can specify an integer
constant here to have a specific number of rows fetched (numrows
), or use any of the following keywords:
ALL
The keyword used to retrieve all rows.
NEXT
The keyword used to retrieve the row immediately following the current position.
PRIOR
The keyword used to retrieve the row immediately preceding the current position.
cursor
The name of an open cursor you wish to use for the FETCH
.
A successful FETCH
command returns any query results generated by the
specified cursor. If the query fails, one of the following messages will be displayed:
NOTICE: PerformPortalFetch: portal "
cursor
" not found
The notice returned if the specified cursor has not yet been declared. Remember that you must declare a cursor within a transaction block before it can be used.
NOTICE: FETCH/ABSOLUTE not supported, using RELATIVE
The notice returned if you attempt to use absolute positioning with the ABSOLUTE
keyword in place of the RELATIVE
keyword.
PostgreSQL does not currently support absolute positioning of cursors (which would move a
cursor to a specific row offset in a result set, rather than a row relative to the current
cursor position).
ERROR: FETCH/RELATIVE at current position is not supported
The error returned if you attempt to pass 0 as the number of rows to fetch, with the
RELATIVE
direction specified. This happens because the FETCH
RELATIVE 0 FROM cursor
syntax is defined within SQL92 as allowing a user to
continually retrieve the row which is at the cursor’s current position.
PostgreSQL does not support the use of this syntax; used without the RELATIVE
keyword, instead of returning the current position’s row, the use of
0 indicates to the database that you wish to retrieve all rows. Used
with the RELATIVE
keyword, however, PostgreSQL assumes you are instead
trying to use the SQL92 defined functionality and displays this error instead of fetching
all rows.
Use the FETCH
command to retrieve a specified number of rows using a
cursor. You always need to be within a transaction while using cursors, as the data they store
is not independent of other users within the system. The number of rows you specify can be
either positive or negative. A positive number will fetch from whatever direction you specify
with the direction parameter (if you don’t specify a direction, FORWARD
will be used by default).
A negative number will take you in the opposite direction as that specified by the
direction
parameter. For example, specifying
FORWARD -5
has the same effect as specifying BACKWARD
5
. If the number of rows you specify is greater than the number of rows remaining to
be retrieved, the FETCH
command will return all those remaining.
The following examples assume a transaction and an already-defined cursor (named cur_employee
) that returns rows from the employees
table.
The following example fetches the first two rows in the cur_employee
cursor:
booktown=# BEGIN; BEGIN booktown=# DECLARE cur_employee CURSOR FOR booktown-# SELECT first_name, last_name FROM employees; SELECT booktown=# FETCH FORWARD 2 IN cur_employee; first_name | last_name ------------+----------- Vincent | Appel Michael | Holloway (2 rows)
The following example uses BACKWARD -2
(a double negative) to then
fetch two rows in the forward direction:
booktown=# FETCH BACKWARD -2 IN cur_employee;
first_name | last_name
------------+-----------
David | Joble
Ben | Noble
(2 rows)
The next example demonstrates how to actually fetch backwards in the cur_employee
cursor:
booktown=# FETCH BACKWARD 3 IN cur_employee;
first_name | last_name
------------+-----------
David | Joble
Michael | Holloway
Vincent | Appel
(3 rows)
18.223.196.146