granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/fetch.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/fetch.sgml,v 1.22 2002/12/30 15:31:47 momjian Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-FETCH">
   7  <refmeta>
   8   <refentrytitle id="SQL-FETCH-TITLE">FETCH</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11  <refnamediv>
  12   <refname>
  13    FETCH
  14   </refname>
  15   <refpurpose>
  16    retrieve rows from a table using a cursor
  17   </refpurpose>
  18  </refnamediv>
  19  <refsynopsisdiv>
  20   <refsynopsisdivinfo>
  21    <date>1999-07-20</date>
  22   </refsynopsisdivinfo>
  23   <synopsis>
  24 FETCH [ <replaceable class="PARAMETER">direction</replaceable> ] [ <replaceable class="PARAMETER">count</replaceable> ] { IN | FROM } <replaceable class="PARAMETER">cursor</replaceable>
  25 FETCH [ FORWARD | BACKWARD | RELATIVE ] [ <replaceable class="PARAMETER">#</replaceable> | ALL | NEXT | PRIOR ]
  26     { IN | FROM } <replaceable class="PARAMETER">cursor</replaceable>
  27   </synopsis>
  28
  29   <refsect2 id="R2-SQL-FETCH-1">
  30    <refsect2info>
  31     <date>1998-09-01</date>
  32    </refsect2info>
  33    <title>
  34     Inputs
  35    </title>
  36    <para>
  37
  38     <variablelist>
  39      <varlistentry>
  40       <term><replaceable class="PARAMETER">direction</replaceable></term>
  41       <listitem>
  42        <para>
  43         <replaceable class="PARAMETER">selector</replaceable>
  44         defines the fetch direction. It can be one of
  45         the following:
  46
  47         <variablelist>
  48          <varlistentry>
  49           <term>FORWARD</term>
  50           <listitem>
  51            <para>
  52             fetch next row(s). This is the default
  53             if <replaceable class="PARAMETER">selector</replaceable> is omitted.
  54            </para>
  55           </listitem>
  56          </varlistentry>
  57          <varlistentry>
  58           <term>BACKWARD</term>
  59           <listitem>
  60            <para>
  61             fetch previous row(s).
  62            </para>
  63           </listitem>
  64          </varlistentry>
  65          <varlistentry>
  66           <term>RELATIVE</term>
  67           <listitem>
  68            <para>
  69             Noise word for SQL92 compatibility.
  70            </para>
  71           </listitem>
  72          </varlistentry>
  73         </variablelist>
  74        </para>
  75       </listitem>
  76      </varlistentry>
  77
  78      <varlistentry>
  79       <term><replaceable class="PARAMETER">count</replaceable></term>
  80       <listitem>
  81        <para>
  82         <replaceable class="PARAMETER">count</replaceable>
  83         determines how many rows to fetch. It can be one of the following:
  84
  85         <variablelist>
  86          <varlistentry>
  87           <term><replaceable class="PARAMETER">#</replaceable></term>
  88           <listitem>
  89            <para>
  90             A signed integer that specifies how many rows to fetch.
  91             Note that a negative integer is equivalent to changing the sense of
  92             FORWARD and BACKWARD. Zero re-fetches the current row.
  93            </para>
  94           </listitem>
  95          </varlistentry>
  96
  97          <varlistentry>
  98           <term>
  99            ALL
 100           </term>
 101           <listitem>
 102            <para>
 103             Retrieve all remaining rows.
 104            </para>
 105           </listitem>
 106          </varlistentry>
 107
 108          <varlistentry>
 109           <term>
 110            NEXT
 111           </term>
 112           <listitem>
 113            <para>
 114             Equivalent to specifying a count of <command>1</command>.
 115            </para>
 116           </listitem>
 117          </varlistentry>
 118
 119          <varlistentry>
 120           <term>
 121            PRIOR
 122           </term>
 123           <listitem>
 124            <para>
 125             Equivalent to specifying a count of <command>-1</command>.
 126            </para>
 127           </listitem>
 128          </varlistentry>
 129         </variablelist>
 130        </para>
 131       </listitem>
 132      </varlistentry>
 133
 134      <varlistentry>
 135       <term><replaceable class="PARAMETER">cursor</replaceable></term>
 136       <listitem>
 137        <para>
 138         An open cursor's name.
 139        </para>
 140       </listitem>
 141      </varlistentry>
 142     </variablelist>
 143    </para>
 144   </refsect2>
 145
 146   <refsect2 id="R2-SQL-FETCH-2">
 147    <refsect2info>
 148     <date>1998-04-15</date>
 149    </refsect2info>
 150    <title>
 151     Outputs
 152    </title>
 153    <para>
 154     <command>FETCH</command> returns the results of the query defined by the specified cursor.
 155     The following messages will be returned if the query fails:
 156
 157     <variablelist>
 158      <varlistentry>
 159       <term><computeroutput>
 160 WARNING:  PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found
 161        </computeroutput></term>
 162       <listitem>
 163        <para>
 164         If <replaceable class="PARAMETER">cursor</replaceable>
 165         is not previously declared.
 166         The cursor must be declared within a transaction block.
 167        </para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172       <term><computeroutput>
 173 WARNING:  FETCH/ABSOLUTE not supported, using RELATIVE
 174        </computeroutput></term>
 175       <listitem>
 176        <para>
 177         <productname>PostgreSQL</productname> does not support absolute
 178         positioning of cursors.
 179        </para>
 180       </listitem>
 181      </varlistentry>
 182
 183     </variablelist>
 184    </para>
 185   </refsect2>
 186  </refsynopsisdiv>
 187
 188  <refsect1 id="R1-SQL-FETCH-1">
 189   <refsect1info>
 190    <date>1998-04-15</date>
 191   </refsect1info>
 192   <title>
 193    Description
 194   </title>
 195
 196   <para>
 197    <command>FETCH</command> allows a user to retrieve rows using a cursor.
 198    The number of rows retrieved is specified by
 199    <replaceable class="PARAMETER">#</replaceable>.
 200    If the number of rows remaining in the cursor is less
 201    than <replaceable class="PARAMETER">#</replaceable>,
 202    then only those available are fetched.
 203    Substituting the keyword ALL in place of a number will
 204    cause all remaining rows in the cursor to be retrieved.
 205    Instances may be fetched in both FORWARD and BACKWARD
 206    directions. The default direction is FORWARD.
 207
 208    <tip>
 209     <para>
 210      Negative numbers are allowed to be specified for the
 211      row count. A negative number is equivalent to reversing
 212      the sense of the FORWARD and BACKWARD keywords. For example,
 213      <command>FORWARD -1</command> is the same as <command>BACKWARD 1</command>.
 214     </para>
 215    </tip>
 216   </para>
 217
 218   <refsect2 id="R2-SQL-FETCH-3">
 219    <refsect2info>
 220     <date>1998-04-15</date>
 221    </refsect2info>
 222    <title>
 223     Notes
 224    </title>
 225
 226    <para>
 227     Note that the FORWARD and BACKWARD keywords are
 228     <productname>PostgreSQL</productname> extensions.
 229     The <acronym>SQL92</acronym> syntax is also supported, specified
 230     in the second form of the command. See below for details
 231     on compatibility issues.
 232    </para>
 233
 234    <para>
 235     Updating data in a cursor is not supported by
 236     <productname>PostgreSQL</productname>,
 237     because mapping cursor updates back to base tables is
 238     not generally possible, as is also the case with VIEW updates.
 239     Consequently,
 240     users must issue explicit UPDATE commands to replace data.
 241    </para>
 242
 243    <para>
 244     Cursors may only be used inside of transactions because
 245     the data that they store spans multiple user queries.
 246    </para>
 247
 248    <para>
 249     Use
 250     <xref linkend="sql-move" endterm="sql-move-title">
 251     to change cursor position.
 252     <xref linkend="sql-declare" endterm="sql-declare-title">
 253     will define a cursor.
 254     Refer to
 255     <xref linkend="sql-begin" endterm="sql-begin-title">,
 256     <xref linkend="sql-commit" endterm="sql-commit-title">,
 257     and
 258     <xref linkend="sql-rollback" endterm="sql-rollback-title">
 259     for further information about transactions.
 260    </para>
 261   </refsect2>
 262  </refsect1>
 263
 264  <refsect1 id="R1-SQL-FETCH-2">
 265   <title>
 266    Usage
 267   </title>
 268
 269   <para>
 270    The following examples traverses a table using a cursor.
 271
 272 <programlisting>
 273 -- Set up and use a cursor:
 274
 275 BEGIN WORK;
 276 DECLARE liahona CURSOR FOR SELECT * FROM films;
 277
 278 -- Fetch first 5 rows in the cursor liahona:
 279 FETCH FORWARD 5 IN liahona;
 280
 281 <computeroutput>
 282  code  |          title          | did | date_prod  |  kind    | len
 283 -------+-------------------------+-----+------------+----------+-------
 284  BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
 285  BL102 | The African Queen       | 101 | 1951-08-11 | Romantic | 01:43
 286  JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
 287  P_301 | Vertigo                 | 103 | 1958-11-14 | Action   | 02:08
 288  P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28
 289 </computeroutput>
 290
 291 -- Fetch previous row:
 292 FETCH BACKWARD 1 IN liahona;
 293
 294 <computeroutput>
 295  code  | title   | did | date_prod  | kind   | len
 296 -------+---------+-----+------------+--------+-------
 297  P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
 298 </computeroutput>
 299
 300 -- close the cursor and commit work:
 301
 302 CLOSE liahona;
 303 COMMIT WORK;
 304 </programlisting>
 305   </para>
 306  </refsect1>
 307
 308  <refsect1 id="R1-SQL-FETCH-3">
 309   <title>
 310    Compatibility
 311   </title>
 312
 313   <refsect2 id="R2-SQL-FETCH-4">
 314    <refsect2info>
 315     <date>1998-09-01</date>
 316    </refsect2info>
 317    <title>
 318     SQL92
 319    </title>
 320
 321    <para>
 322     <note>
 323      <para>
 324       The non-embedded use of cursors is a <productname>PostgreSQL</productname>
 325       extension. The syntax and usage of cursors is being compared
 326       against the embedded form of cursors defined in <acronym>SQL92</acronym>.
 327      </para>
 328     </note>
 329    </para>
 330
 331    <para>
 332     <acronym>SQL92</acronym> allows absolute positioning of the cursor for
 333     FETCH, and allows placing the results into explicit variables:
 334
 335     <synopsis>
 336 FETCH ABSOLUTE <replaceable class="PARAMETER">#</replaceable>
 337     FROM <replaceable class="PARAMETER">cursor</replaceable>
 338     INTO :<replaceable class="PARAMETER">variable</replaceable> [, ...]
 339     </synopsis>
 340
 341     <variablelist>
 342      <varlistentry>
 343       <term>ABSOLUTE</term>
 344       <listitem>
 345        <para>
 346         The cursor should be positioned to the specified absolute
 347         row number. All row numbers in <productname>PostgreSQL</productname>
 348         are relative numbers so this capability is not supported.
 349        </para>
 350       </listitem>
 351      </varlistentry>
 352      <varlistentry>
 353       <term>:<replaceable class="PARAMETER">variable</replaceable></term>
 354       <listitem>
 355        <para>
 356         Target host variable(s).
 357        </para>
 358       </listitem>
 359      </varlistentry>
 360     </variablelist>
 361    </para>
 362   </refsect2>
 363  </refsect1>
 364 </refentry>
 365
 366 <!-- Keep this comment at the end of the file
 367 Local variables:
 368 mode: sgml
 369 sgml-omittag:nil
 370 sgml-shorttag:t
 371 sgml-minimize-attributes:nil
 372 sgml-always-quote-attributes:t
 373 sgml-indent-step:1
 374 sgml-indent-data:t
 375 sgml-parent-document:nil
 376 sgml-default-dtd-file:"../reference.ced"
 377 sgml-exposed-tags:nil
 378 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 379 sgml-local-ecat-files:nil
 380 End:
 381 -->