Synopsis
FETCH direction
[ count ] { IN | FROM } cursor
direction ::= { FORWARD | BACKWARD | RELATIVE }
count ::= { numrows | ALL | NEXT | PRIOR }Parameters
- 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.
Results
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.
Description
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.
Note: As of PostgreSQL 7.1.x, you cannot update data using a cursor.
Examples
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)
