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.27 2003/03/11 19:40:22 tgl 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 query using a cursor
  17   </refpurpose>
  18  </refnamediv>
  19  <refsynopsisdiv>
  20   <refsynopsisdivinfo>
  21    <date>2003-03-11</date>
  22   </refsynopsisdivinfo>
  23   <synopsis>
  24 FETCH [ <replaceable class="PARAMETER">direction</replaceable> { FROM | IN } ] <replaceable class="PARAMETER">cursor</replaceable>
  25
  26 where <replaceable class="PARAMETER">direction</replaceable> can be empty or one of:
  27
  28     NEXT
  29     PRIOR
  30     FIRST
  31     LAST
  32     ABSOLUTE <replaceable class="PARAMETER">count</replaceable>
  33     RELATIVE <replaceable class="PARAMETER">count</replaceable>
  34     <replaceable class="PARAMETER">count</replaceable>
  35     ALL
  36     FORWARD
  37     FORWARD <replaceable class="PARAMETER">count</replaceable>
  38     FORWARD ALL
  39     BACKWARD
  40     BACKWARD <replaceable class="PARAMETER">count</replaceable>
  41     BACKWARD ALL
  42   </synopsis>
  43
  44   <refsect2 id="R2-SQL-FETCH-1">
  45    <refsect2info>
  46     <date>2003-03-11</date>
  47    </refsect2info>
  48    <title>
  49     Inputs
  50    </title>
  51    <para>
  52
  53     <variablelist>
  54      <varlistentry>
  55       <term><replaceable class="PARAMETER">direction</replaceable></term>
  56       <listitem>
  57        <para>
  58         <replaceable class="PARAMETER">direction</replaceable>
  59         defines the fetch direction and number of rows to fetch.
  60         It can be one of the following:
  61
  62         <variablelist>
  63          <varlistentry>
  64           <term>NEXT</term>
  65           <listitem>
  66            <para>
  67             fetch next row. This is the default
  68             if <replaceable class="PARAMETER">direction</replaceable> is omitted.
  69            </para>
  70           </listitem>
  71          </varlistentry>
  72
  73          <varlistentry>
  74           <term>PRIOR</term>
  75           <listitem>
  76            <para>
  77             fetch prior row.
  78            </para>
  79           </listitem>
  80          </varlistentry>
  81
  82          <varlistentry>
  83           <term>FIRST</term>
  84           <listitem>
  85            <para>
  86             fetch first row of query (same as ABSOLUTE 1).
  87            </para>
  88           </listitem>
  89          </varlistentry>
  90
  91          <varlistentry>
  92           <term>LAST</term>
  93           <listitem>
  94            <para>
  95             fetch last row of query (same as ABSOLUTE -1).
  96            </para>
  97           </listitem>
  98          </varlistentry>
  99
 100          <varlistentry>
 101           <term>ABSOLUTE <replaceable class="PARAMETER">count</replaceable></term>
 102           <listitem>
 103            <para>
 104             fetch the <replaceable class="PARAMETER">count</replaceable>'th
 105             row of query, or the
 106             abs(<replaceable class="PARAMETER">count</replaceable>)'th row
 107             from the end if
 108             <replaceable class="PARAMETER">count</replaceable> &lt; 0.
 109             Position before first row or after last row
 110             if <replaceable class="PARAMETER">count</replaceable> is out of
 111             range; in particular, ABSOLUTE 0 positions before first row.
 112            </para>
 113           </listitem>
 114          </varlistentry>
 115
 116          <varlistentry>
 117           <term>RELATIVE <replaceable class="PARAMETER">count</replaceable></term>
 118           <listitem>
 119            <para>
 120             fetch the <replaceable class="PARAMETER">count</replaceable>'th
 121             succeeding row, or the
 122             abs(<replaceable class="PARAMETER">count</replaceable>)'th prior
 123             row if <replaceable class="PARAMETER">count</replaceable> &lt; 0.
 124             RELATIVE 0 re-fetches current row, if any.
 125            </para>
 126           </listitem>
 127          </varlistentry>
 128
 129          <varlistentry>
 130           <term><replaceable class="PARAMETER">count</replaceable></term>
 131           <listitem>
 132            <para>
 133             fetch the next <replaceable class="PARAMETER">count</replaceable>
 134             rows (same as FORWARD <replaceable class="PARAMETER">count</replaceable>).
 135            </para>
 136           </listitem>
 137          </varlistentry>
 138
 139          <varlistentry>
 140           <term>ALL</term>
 141           <listitem>
 142            <para>
 143             fetch all remaining rows (same as FORWARD ALL).
 144            </para>
 145           </listitem>
 146          </varlistentry>
 147
 148          <varlistentry>
 149           <term>FORWARD</term>
 150           <listitem>
 151            <para>
 152             fetch next row (same as NEXT).
 153            </para>
 154           </listitem>
 155          </varlistentry>
 156
 157          <varlistentry>
 158           <term>FORWARD <replaceable class="PARAMETER">count</replaceable></term>
 159           <listitem>
 160            <para>
 161             fetch next <replaceable class="PARAMETER">count</replaceable>
 162             rows.  FORWARD 0 re-fetches current row.
 163            </para>
 164           </listitem>
 165          </varlistentry>
 166
 167          <varlistentry>
 168           <term>FORWARD ALL</term>
 169           <listitem>
 170            <para>
 171             fetch all remaining rows.
 172            </para>
 173           </listitem>
 174          </varlistentry>
 175
 176          <varlistentry>
 177           <term>BACKWARD</term>
 178           <listitem>
 179            <para>
 180             fetch prior row (same as PRIOR).
 181            </para>
 182           </listitem>
 183          </varlistentry>
 184
 185          <varlistentry>
 186           <term>BACKWARD <replaceable class="PARAMETER">count</replaceable></term>
 187           <listitem>
 188            <para>
 189             fetch prior <replaceable class="PARAMETER">count</replaceable>
 190             rows (scanning backwards).  BACKWARD 0 re-fetches current row.
 191            </para>
 192           </listitem>
 193          </varlistentry>
 194
 195          <varlistentry>
 196           <term>BACKWARD ALL</term>
 197           <listitem>
 198            <para>
 199             fetch all prior rows (scanning backwards).
 200            </para>
 201           </listitem>
 202          </varlistentry>
 203
 204         </variablelist>
 205        </para>
 206       </listitem>
 207      </varlistentry>
 208
 209      <varlistentry>
 210       <term><replaceable class="PARAMETER">count</replaceable></term>
 211       <listitem>
 212        <para>
 213         <replaceable class="PARAMETER">count</replaceable>
 214         is a possibly-signed integer constant, determining the location
 215         or number of rows to fetch.  For FORWARD and BACKWARD cases,
 216         specifying a negative <replaceable
 217         class="PARAMETER">count</replaceable>
 218         is equivalent to changing the sense of FORWARD and BACKWARD.
 219        </para>
 220       </listitem>
 221      </varlistentry>
 222
 223      <varlistentry>
 224       <term><replaceable class="PARAMETER">cursor</replaceable></term>
 225       <listitem>
 226        <para>
 227         An open cursor's name.
 228        </para>
 229       </listitem>
 230      </varlistentry>
 231     </variablelist>
 232    </para>
 233   </refsect2>
 234
 235   <refsect2 id="R2-SQL-FETCH-2">
 236    <refsect2info>
 237     <date>2003-03-11</date>
 238    </refsect2info>
 239    <title>
 240     Outputs
 241    </title>
 242    <para>
 243     <command>FETCH</command> returns rows from the result of the query defined
 244     by the specified cursor.
 245     The following messages will be returned if the query fails:
 246
 247     <variablelist>
 248      <varlistentry>
 249       <term><computeroutput>
 250 WARNING:  PerformPortalFetch: portal "<replaceable class="PARAMETER">cursor</replaceable>" not found
 251        </computeroutput></term>
 252       <listitem>
 253        <para>
 254         If <replaceable class="PARAMETER">cursor</replaceable> is not known.
 255         The cursor must have been declared within the current transaction block.
 256        </para>
 257       </listitem>
 258      </varlistentry>
 259     </variablelist>
 260    </para>
 261   </refsect2>
 262  </refsynopsisdiv>
 263
 264  <refsect1 id="R1-SQL-FETCH-1">
 265   <refsect1info>
 266    <date>2003-03-11</date>
 267   </refsect1info>
 268   <title>
 269    Description
 270   </title>
 271
 272   <para>
 273    <command>FETCH</command> retrieves rows using a cursor.
 274   </para>
 275
 276   <para>
 277    A cursor has an associated <firstterm>position</> that is used by
 278    <command>FETCH</>.  The cursor position can be before the first row of the
 279    query result, or on any particular row of the result, or after the last row
 280    of the result.  When created, a cursor is positioned before the first row.
 281    After fetching some rows, the cursor is positioned on the row most recently
 282    retrieved.  If <command>FETCH</> runs off the end of the available rows
 283    then the cursor is left positioned after the last row, or before the first
 284    row if fetching backward.  <command>FETCH ALL</> or <command>FETCH BACKWARD
 285    ALL</> will always leave the cursor positioned after the last row or before
 286    the first row.
 287   </para>
 288
 289   <para>
 290    The SQL-compatible forms (NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE)
 291    fetch a single row after moving the cursor appropriately.  If there is
 292    no such row, an empty result is returned, and the cursor is left positioned
 293    before the first row or after the last row as appropriate.
 294   </para>
 295
 296   <para>
 297    The forms using FORWARD and BACKWARD are not in the SQL standard, but
 298    are <productname>PostgreSQL</productname> extensions.  These forms
 299    retrieve the indicated number of rows moving in the forward or backward
 300    direction, leaving the cursor positioned on the last-returned row
 301    (or after/before all rows, if the <replaceable
 302    class="PARAMETER">count</replaceable> exceeds the number of rows
 303    available).
 304   </para>
 305
 306    <tip>
 307     <para>
 308      RELATIVE 0, FORWARD 0, and BACKWARD 0 all request
 309      fetching the current row without moving the
 310      cursor --- that is, re-fetching the most recently fetched row.
 311      This will succeed unless the cursor is positioned before the
 312      first row or after the last row; in which case, no row is returned.
 313     </para>
 314    </tip>
 315
 316   <refsect2 id="R2-SQL-FETCH-3">
 317    <refsect2info>
 318     <date>2003-03-11</date>
 319    </refsect2info>
 320    <title>
 321     Notes
 322    </title>
 323
 324    <para>
 325     The cursor should be declared with the SCROLL option if one intends to
 326     use any variants of <command>FETCH</> other than <command>FETCH NEXT</>
 327     or <command>FETCH FORWARD</> with a positive count.  For simple queries
 328     <productname>PostgreSQL</productname> will allow backwards fetch from
 329     cursors not declared with SCROLL, but this behavior is best not relied on.
 330    </para>
 331
 332    <para>
 333     ABSOLUTE fetches are not any faster than navigating to the desired row
 334     with a relative move: the underlying implementation must traverse all
 335     the intermediate rows anyway.  Negative absolute fetches are even worse:
 336     the query must be read to the end to find the last row, and then
 337     traversed backward from there.  However, rewinding to the start of the
 338     query (as with FETCH ABSOLUTE 0) is fast.
 339    </para>
 340
 341    <para>
 342     Updating data via a cursor is not supported by
 343     <productname>PostgreSQL</productname>,
 344     because mapping cursor updates back to base tables is
 345     not generally possible, as is also the case with VIEW updates.
 346     Consequently,
 347     users must issue explicit UPDATE commands to replace data.
 348    </para>
 349
 350    <para>
 351     Cursors may only be used inside transaction blocks.
 352    </para>
 353
 354    <para>
 355     <xref linkend="sql-declare" endterm="sql-declare-title">
 356     is used to define a cursor.
 357     Use
 358     <xref linkend="sql-move" endterm="sql-move-title">
 359     to change cursor position without retrieving data.
 360     Refer to
 361     <xref linkend="sql-begin" endterm="sql-begin-title">,
 362     <xref linkend="sql-commit" endterm="sql-commit-title">,
 363     and
 364     <xref linkend="sql-rollback" endterm="sql-rollback-title">
 365     for further information about transactions.
 366    </para>
 367   </refsect2>
 368  </refsect1>
 369
 370  <refsect1 id="R1-SQL-FETCH-2">
 371   <title>
 372    Usage
 373   </title>
 374
 375   <para>
 376    The following example traverses a table using a cursor.
 377
 378 <programlisting>
 379 -- Set up and use a cursor:
 380
 381 BEGIN WORK;
 382 DECLARE liahona CURSOR FOR SELECT * FROM films;
 383
 384 -- Fetch first 5 rows in the cursor liahona:
 385 FETCH FORWARD 5 IN liahona;
 386
 387 <computeroutput>
 388  code  |          title          | did | date_prod  |  kind    | len
 389 -------+-------------------------+-----+------------+----------+-------
 390  BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
 391  BL102 | The African Queen       | 101 | 1951-08-11 | Romantic | 01:43
 392  JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
 393  P_301 | Vertigo                 | 103 | 1958-11-14 | Action   | 02:08
 394  P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28
 395 </computeroutput>
 396
 397 -- Fetch previous row:
 398 FETCH PRIOR FROM liahona;
 399
 400 <computeroutput>
 401  code  | title   | did | date_prod  | kind   | len
 402 -------+---------+-----+------------+--------+-------
 403  P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08
 404 </computeroutput>
 405
 406 -- close the cursor and commit work:
 407
 408 CLOSE liahona;
 409 COMMIT WORK;
 410 </programlisting>
 411   </para>
 412  </refsect1>
 413
 414  <refsect1 id="R1-SQL-FETCH-3">
 415   <title>
 416    Compatibility
 417   </title>
 418
 419   <refsect2 id="R2-SQL-FETCH-4">
 420    <refsect2info>
 421     <date>2003-03-11</date>
 422    </refsect2info>
 423    <title>
 424     SQL92
 425    </title>
 426
 427    <para>
 428     <acronym>SQL92</acronym> defines FETCH for use in embedded contexts only.
 429     Therefore, it describes placing the results into explicit variables using
 430     an <literal>INTO</> clause, for example:
 431
 432     <synopsis>
 433 FETCH ABSOLUTE <replaceable class="PARAMETER">n</replaceable>
 434     FROM <replaceable class="PARAMETER">cursor</replaceable>
 435     INTO :<replaceable class="PARAMETER">variable</replaceable> [, ...]
 436     </synopsis>
 437
 438     <productname>PostgreSQL</productname>'s use of non-embedded cursors
 439     is non-standard, and so is its practice of returning the result data
 440     as if it were a SELECT result.  Other than this point, FETCH is fully
 441     upward-compatible with <acronym>SQL92</acronym>.
 442    </para>
 443
 444    <para>
 445     The FETCH forms involving FORWARD and BACKWARD (including the forms
 446     FETCH <replaceable class="PARAMETER">count</replaceable> and FETCH ALL,
 447     in which FORWARD is implicit) are <productname>PostgreSQL</productname>
 448     extensions.
 449    </para>
 450
 451    <para>
 452     <acronym>SQL92</acronym> allows only <literal>FROM</> preceding the
 453     cursor name; the option to use <literal>IN</> is an extension.
 454    </para>
 455   </refsect2>
 456  </refsect1>
 457 </refentry>
 458
 459 <!-- Keep this comment at the end of the file
 460 Local variables:
 461 mode: sgml
 462 sgml-omittag:nil
 463 sgml-shorttag:t
 464 sgml-minimize-attributes:nil
 465 sgml-always-quote-attributes:t
 466 sgml-indent-step:1
 467 sgml-indent-data:t
 468 sgml-parent-document:nil
 469 sgml-default-dtd-file:"../reference.ced"
 470 sgml-exposed-tags:nil
 471 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 472 sgml-local-ecat-files:nil
 473 End:
 474 -->