begriffs open source - ai-pg/blob - full-docs/src/sgml/html/libpq-single-row-mode.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>32.6. Retrieving Query Results in Chunks</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode" /><link rel="next" href="libpq-cancel.html" title="32.7. Canceling Queries in Progress" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">32.6. Retrieving Query Results in Chunks</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><th width="60%" align="center">Chapter 32. <span class="application">libpq</span> — C Library</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="32.7. Canceling Queries in Progress">Next</a></td></tr></table><hr /></div><div class="sect1" id="LIBPQ-SINGLE-ROW-MODE"><div class="titlepage"><div><div><h2 class="title" style="clear: both">32.6. Retrieving Query Results in Chunks <a href="#LIBPQ-SINGLE-ROW-MODE" class="id_link">#</a></h2></div></div></div><a id="id-1.7.3.13.2" class="indexterm"></a><a id="id-1.7.3.13.3" class="indexterm"></a><p>
   3    Ordinarily, <span class="application">libpq</span> collects an SQL command's
   4    entire result and returns it to the application as a single
   5    <code class="structname">PGresult</code>.  This can be unworkable for commands
   6    that return a large number of rows.  For such cases, applications can use
   7    <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> and <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> in
   8    <em class="firstterm">single-row mode</em> or <em class="firstterm">chunked
   9    mode</em>.  In these modes, result row(s) are returned to the
  10    application as they are received from the server, one at a time for
  11    single-row mode or in groups for chunked mode.
  12   </p><p>
  13    To enter one of these modes, call <a class="xref" href="libpq-single-row-mode.html#LIBPQ-PQSETSINGLEROWMODE"><code class="function">PQsetSingleRowMode</code></a>
  14     or <a class="xref" href="libpq-single-row-mode.html#LIBPQ-PQSETCHUNKEDROWSMODE"><code class="function">PQsetChunkedRowsMode</code></a>
  15    immediately after a successful call of <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a>
  16    (or a sibling function).  This mode selection is effective only for the
  17    currently executing query.  Then call <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>
  18    repeatedly, until it returns null, as documented in <a class="xref" href="libpq-async.html" title="32.4. Asynchronous Command Processing">Section 32.4</a>.  If the query returns any rows, they are returned
  19    as one or more <code class="structname">PGresult</code> objects, which look like
  20    normal query results except for having status code
  21    <code class="literal">PGRES_SINGLE_TUPLE</code> for single-row mode or
  22    <code class="literal">PGRES_TUPLES_CHUNK</code> for chunked mode, instead of
  23    <code class="literal">PGRES_TUPLES_OK</code>.  There is exactly one result row in
  24    each <code class="literal">PGRES_SINGLE_TUPLE</code> object, while
  25    a <code class="literal">PGRES_TUPLES_CHUNK</code> object contains at least one
  26    row but not more than the specified number of rows per chunk.
  27    After the last row, or immediately if
  28    the query returns zero rows, a zero-row object with status
  29    <code class="literal">PGRES_TUPLES_OK</code> is returned; this is the signal that no
  30    more rows will arrive.  (But note that it is still necessary to continue
  31    calling <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a> until it returns null.)  All of
  32    these <code class="structname">PGresult</code> objects will contain the same row
  33    description data (column names, types, etc.) that an ordinary
  34    <code class="structname">PGresult</code> object for the query would have.
  35    Each object should be freed with <a class="xref" href="libpq-exec.html#LIBPQ-PQCLEAR"><code class="function">PQclear</code></a> as usual.
  36   </p><p>
  37    When using pipeline mode, single-row or chunked mode needs to be
  38    activated for each query in the pipeline before retrieving results for
  39    that query with <code class="function">PQgetResult</code>.
  40    See <a class="xref" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode">Section 32.5</a> for more information.
  41   </p><p>
  42    </p><div class="variablelist"><dl class="variablelist"><dt id="LIBPQ-PQSETSINGLEROWMODE"><span class="term"><code class="function">PQsetSingleRowMode</code><a id="id-1.7.3.13.7.1.1.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETSINGLEROWMODE" class="id_link">#</a></dt><dd><p>
  43        Select single-row mode for the currently-executing query.
  44
  45 </p><pre class="synopsis">
  46 int PQsetSingleRowMode(PGconn *conn);
  47 </pre><p>
  48       </p><p>
  49        This function can only be called immediately after
  50        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> or one of its sibling functions,
  51        before any other operation on the connection such as
  52        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
  53      </a> or
  54        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.  If called at the correct time,
  55        the function activates single-row mode for the current query and
  56        returns 1.  Otherwise the mode stays unchanged and the function
  57        returns 0.  In any case, the mode reverts to normal after
  58        completion of the current query.
  59       </p></dd><dt id="LIBPQ-PQSETCHUNKEDROWSMODE"><span class="term"><code class="function">PQsetChunkedRowsMode</code><a id="id-1.7.3.13.7.1.2.1.2" class="indexterm"></a></span> <a href="#LIBPQ-PQSETCHUNKEDROWSMODE" class="id_link">#</a></dt><dd><p>
  60        Select chunked mode for the currently-executing query.
  61
  62 </p><pre class="synopsis">
  63 int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
  64 </pre><p>
  65       </p><p>
  66        This function is similar to
  67        <a class="xref" href="libpq-single-row-mode.html#LIBPQ-PQSETSINGLEROWMODE"><code class="function">PQsetSingleRowMode</code></a>, except that it
  68        specifies retrieval of up to <em class="replaceable"><code>chunkSize</code></em> rows
  69        per <code class="structname">PGresult</code>, not necessarily just one row.
  70        This function can only be called immediately after
  71        <a class="xref" href="libpq-async.html#LIBPQ-PQSENDQUERY"><code class="function">PQsendQuery</code></a> or one of its sibling functions,
  72        before any other operation on the connection such as
  73        <a class="xref" href="libpq-async.html#LIBPQ-PQCONSUMEINPUT"><code class="function">PQconsumeInput</code>
  74      </a> or
  75        <a class="xref" href="libpq-async.html#LIBPQ-PQGETRESULT"><code class="function">PQgetResult</code></a>.  If called at the correct time,
  76        the function activates chunked mode for the current query and
  77        returns 1.  Otherwise the mode stays unchanged and the function
  78        returns 0.  In any case, the mode reverts to normal after
  79        completion of the current query.
  80       </p></dd></dl></div><p>
  81   </p><div class="caution"><h3 class="title">Caution</h3><p>
  82     While processing a query, the server may return some rows and then
  83     encounter an error, causing the query to be aborted.  Ordinarily,
  84     <span class="application">libpq</span> discards any such rows and reports only the
  85     error.  But in single-row or chunked mode, some rows may have already
  86     been returned to the application. Hence, the application will see some
  87     <code class="literal">PGRES_SINGLE_TUPLE</code> or <code class="literal">PGRES_TUPLES_CHUNK</code>
  88     <code class="structname">PGresult</code>
  89     objects followed by a <code class="literal">PGRES_FATAL_ERROR</code> object.  For
  90     proper transactional behavior, the application must be designed to
  91     discard or undo whatever has been done with the previously-processed
  92     rows, if the query ultimately fails.
  93    </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="libpq-pipeline-mode.html" title="32.5. Pipeline Mode">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="libpq.html" title="Chapter 32. libpq — C Library">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="libpq-cancel.html" title="32.7. Canceling Queries in Progress">Next</a></td></tr><tr><td width="40%" align="left" valign="top">32.5. Pipeline Mode </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 32.7. Canceling Queries in Progress</td></tr></table></div></body></html>