FETCH -- Retrieves rows from a cursor.


FETCH direction
      [ count ] { IN | FROM } cursor

direction ::= { FORWARD | BACKWARD | RELATIVE }
count ::= { numrows | ALL | NEXT | PRIOR }



Use the optional direction parameter to specify the direction you want to fetch. It may be specified as any of the following keywords:


The keyword used to retrieve rows following the current position. This is the default, if the direction is not explicitly set.


The keyword used to retrieve rows preceding the current position.


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).


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:


The keyword used to retrieve all rows.


The keyword used to retrieve the row immediately following the current position.


The keyword used to retrieve the row immediately preceding the current position.


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.


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.

Note: As of PostgreSQL 7.1.x, you cannot update data using a cursor.


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;
booktown=# DECLARE cur_employee CURSOR FOR
booktown-#         SELECT first_name, last_name FROM employees;
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)