Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

FETCH

Name

FETCH -- Retrieves rows from a cursor.

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)

 
 
  Published courtesy of O'Reilly Design by Interspire