mirror of
https://github.com/postgres/postgres.git
synced 2025-12-21 05:21:08 +03:00
408 lines
8.9 KiB
Plaintext
408 lines
8.9 KiB
Plaintext
<REFENTRY ID="SQL-FETCH">
|
|
<REFMETA>
|
|
<REFENTRYTITLE>
|
|
FETCH
|
|
</REFENTRYTITLE>
|
|
<REFMISCINFO>SQL - Language Statements</REFMISCINFO>
|
|
</REFMETA>
|
|
<REFNAMEDIV>
|
|
<REFNAME>
|
|
FETCH
|
|
</REFNAME>
|
|
<REFPURPOSE>
|
|
Gets rows using a cursor
|
|
</REFPURPOSE>
|
|
</refnamediv>
|
|
<REFSYNOPSISDIV>
|
|
<REFSYNOPSISDIVINFO>
|
|
<DATE>1998-09-01</DATE>
|
|
</REFSYNOPSISDIVINFO>
|
|
<SYNOPSIS>
|
|
FETCH [ <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> ] [ <REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE> ]
|
|
{ IN | FROM } <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
FETCH [ RELATIVE ] [ { [ <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE> | ALL | NEXT | PRIOR ] } ]
|
|
FROM ] <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
</SYNOPSIS>
|
|
|
|
<REFSECT2 ID="R2-SQL-FETCH-1">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-01</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Inputs
|
|
</TITLE>
|
|
<PARA>
|
|
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
<REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE>
|
|
defines the fetch direction. It can be one
|
|
the following:
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
FORWARD
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
fetch next row(s). This is the default
|
|
if <REPLACEABLE CLASS="PARAMETER">selector</REPLACEABLE> is omitted.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
BACKWARD
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
fetch previous row(s).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
RELATIVE
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Noise word for SQL92 compatibility.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
<REPLACEABLE CLASS="PARAMETER">count</REPLACEABLE>
|
|
determines how many rows to fetch. It can be one of the following:
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
A signed integer that specify how many rows to fetch.
|
|
Note that a negative integer is equivalent to changing the sense of
|
|
FORWARD and BACKWARD.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
ALL
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Retrieve all remaining rows.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
NEXT
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Equivalent to specifying a count of <command>1</command>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
PRIOR
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Equivalent to specifying a count of <command>-1</command>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
An open cursor's name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</REFSECT2>
|
|
|
|
<REFSECT2 ID="R2-SQL-FETCH-2">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-04-15</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Outputs
|
|
</TITLE>
|
|
<PARA>
|
|
FETCH returns the results of the query defined by the specified cursor.
|
|
The following messages will be returned if the query fails:
|
|
</para>
|
|
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
NOTICE: PerformPortalFetch: portal "<REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>" not found
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
If <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
is not previously declared.
|
|
The cursor must be declared within a transaction block.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
NOTICE: FETCH/ABSOLUTE not supported, using RELATIVE
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
<productname>Postgres</productname> does not support absolute
|
|
positioning of cursors.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
ERROR: FETCH/RELATIVE at current position is not supported
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
<acronym>SQL92</acronym> allows one to repetatively retrieve the cursor
|
|
at its "current position" using the syntax
|
|
<programlisting>
|
|
FETCH RELATIVE 0 FROM <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
</programlisting>
|
|
|
|
<productname>Postgres</productname> does not currently support
|
|
this notion; in fact the value zero is reserved to indicate that
|
|
all rows should be retrieved and is equivalent to specifying the ALL keyword.
|
|
If the RELATIVE keyword has been used, the <productname>Postgres</productname>
|
|
assumes that the user intended <acronym>SQL92</acronym> behavior
|
|
and returns this error message.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</REFSECT2>
|
|
</REFSYNOPSISDIV>
|
|
|
|
<REFSECT1 ID="R1-SQL-FETCH-1">
|
|
<REFSECT1INFO>
|
|
<DATE>1998-04-15</DATE>
|
|
</REFSECT1INFO>
|
|
<TITLE>
|
|
Description
|
|
</TITLE>
|
|
<PARA>
|
|
FETCH allows a user to retrieve rows using a cursor.
|
|
The number of rows retrieved is specified by
|
|
<REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>.
|
|
If the number of rows remaining in the cursor is less
|
|
than <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>,
|
|
then only those available are fetched.
|
|
Substituting the keyword ALL in place of a number will
|
|
cause all remaining rows in the cursor to be retrieved.
|
|
Instances may be fetched in both FORWARD and BACKWARD
|
|
directions. The default direction is FORWARD.
|
|
|
|
<tip>
|
|
<para>
|
|
Negative numbers are now allowed to be specified for the
|
|
row count. A negative number is equivalent to reversing
|
|
the sense of the FORWARD and BACKWARD keywords. For example,
|
|
<command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>.
|
|
</para>
|
|
</tip>
|
|
</para>
|
|
<para>
|
|
Note that the FORWARD and BACKWARD keywords are
|
|
<productname>Postgres</productname> extensions.
|
|
The <acronym>SQL92</acronym> syntax is also supported, specified
|
|
in the second form of the command. See below for details
|
|
on compatibility issues.
|
|
</para>
|
|
<para>
|
|
Once all rows are fetched, every other fetch access returns
|
|
no rows.
|
|
</para>
|
|
|
|
<para>
|
|
Updating data in a cursor is not supported by
|
|
<productname>Postgres</productname>,
|
|
because mapping cursor updates back to base tables is
|
|
not generally possible, as is also the case with VIEW updates.
|
|
Consequently,
|
|
users must issue explicit UPDATE commands to replace data.
|
|
</para>
|
|
|
|
<para>
|
|
Cursors may only be used inside of transactions because
|
|
the data that they store spans multiple user queries.
|
|
</para>
|
|
|
|
<REFSECT2 ID="R2-SQL-FETCH-3">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-04-15</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
Notes
|
|
</TITLE>
|
|
<PARA>
|
|
Refer to MOVE statements to change cursor position.
|
|
Refer to DECLARE statements to declare a cursor.
|
|
Refer to BEGIN WORK, COMMIT WORK, ROLLBACK WORK statements
|
|
for further information about transactions.
|
|
</para>
|
|
</REFSECT2>
|
|
</refsect1>
|
|
|
|
<REFSECT1 ID="R1-SQL-FETCH-2">
|
|
<TITLE>
|
|
Usage
|
|
</TITLE>
|
|
<PARA>
|
|
<ProgramListing>
|
|
--set up and use a cursor:
|
|
--
|
|
BEGIN WORK;
|
|
DECLARE liahona CURSOR
|
|
FOR SELECT * FROM films;
|
|
|
|
--Fetch first 5 rows in the cursor liahona:
|
|
--
|
|
FETCH FORWARD 5 IN liahona;
|
|
|
|
code |title |did| date_prod|kind |len
|
|
-----+-----------------------+---+----------+----------+------
|
|
BL101|The Third Man |101|1949-12-23|Drama | 01:44
|
|
BL102|The African Queen |101|1951-08-11|Romantic | 01:43
|
|
JL201|Une Femme est une Femme|102|1961-03-12|Romantic | 01:25
|
|
P_301|Vertigo |103|1958-11-14|Action | 02:08
|
|
P_302|Becket |103|1964-02-03|Drama | 02:28
|
|
|
|
|
|
--Fetch previous row:
|
|
--
|
|
FETCH BACKWARD 1 IN liahona;
|
|
|
|
code |title |did| date_prod|kind |len
|
|
-----+-----------------------+---+----------+----------+------
|
|
P_301|Vertigo |103|1958-11-14|Action | 02:08
|
|
|
|
-- close the cursor and commit work:
|
|
--
|
|
CLOSE liahona;
|
|
COMMIT WORK;
|
|
</ProgramListing>
|
|
</para>
|
|
</REFSECT1>
|
|
|
|
<REFSECT1 ID="R1-SQL-FETCH-3">
|
|
<TITLE>
|
|
Compatibility
|
|
</TITLE>
|
|
<PARA>
|
|
The non-embedded use of cursors is a <productname>Postgres</productname>
|
|
extension. The syntax and usage of cursors is being compared
|
|
against the embedded form of cursors defined in <acronym>SQL92</acronym>.
|
|
</PARA>
|
|
|
|
<REFSECT2 ID="R2-SQL-FETCH-4">
|
|
<REFSECT2INFO>
|
|
<DATE>1998-09-01</DATE>
|
|
</REFSECT2INFO>
|
|
<TITLE>
|
|
SQL92
|
|
</TITLE>
|
|
<PARA>
|
|
<acronym>SQL92</acronym> allows absolute positioning of the cursor for
|
|
FETCH, and allows placing the results into explicit variables.
|
|
|
|
<synopsis>
|
|
FETCH ABSOLUTE <REPLACEABLE CLASS="PARAMETER">#</REPLACEABLE>
|
|
FROM <REPLACEABLE CLASS="PARAMETER">cursor</REPLACEABLE>
|
|
INTO :<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> [, ...]
|
|
</synopsis>
|
|
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
ABSOLUTE
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
The cursor should be positioned to the specified absolute
|
|
row number. All row numbers in <productname>Postgres</productname>
|
|
are relative numbers so this capability is not supported.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<VARLISTENTRY>
|
|
<TERM>
|
|
:<REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
Target host variable(s).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
</refsect2>
|
|
</refsect1>
|
|
</REFENTRY>
|
|
|
|
<!--
|
|
<REPLACEABLE CLASS="PARAMETER">
|
|
</REPLACEABLE>
|
|
<ReturnValue></ReturnValue>
|
|
<PARA>
|
|
</PARA>
|
|
<VARIABLELIST>
|
|
<VARLISTENTRY>
|
|
<TERM>•
|
|
</TERM>
|
|
<LISTITEM>
|
|
<PARA>
|
|
</PARA>
|
|
</LISTITEM>
|
|
</VARLISTENTRY>
|
|
</VARIABLELIST>
|
|
<PARA>
|
|
</PARA>
|
|
-->
|