begriffs open source - ai-pg/blob - full-docs/txt/libpq-single-row-mode.txt

   1
   2 32.6. Retrieving Query Results in Chunks #
   3
   4    Ordinarily, libpq collects an SQL command's entire result and returns
   5    it to the application as a single PGresult. This can be unworkable for
   6    commands that return a large number of rows. For such cases,
   7    applications can use PQsendQuery and PQgetResult in single-row mode or
   8    chunked mode. In these modes, result row(s) are returned to the
   9    application as they are received from the server, one at a time for
  10    single-row mode or in groups for chunked mode.
  11
  12    To enter one of these modes, call PQsetSingleRowMode or
  13    PQsetChunkedRowsMode immediately after a successful call of PQsendQuery
  14    (or a sibling function). This mode selection is effective only for the
  15    currently executing query. Then call PQgetResult repeatedly, until it
  16    returns null, as documented in Section 32.4. If the query returns any
  17    rows, they are returned as one or more PGresult objects, which look
  18    like normal query results except for having status code
  19    PGRES_SINGLE_TUPLE for single-row mode or PGRES_TUPLES_CHUNK for
  20    chunked mode, instead of PGRES_TUPLES_OK. There is exactly one result
  21    row in each PGRES_SINGLE_TUPLE object, while a PGRES_TUPLES_CHUNK
  22    object contains at least one row but not more than the specified number
  23    of rows per chunk. After the last row, or immediately if the query
  24    returns zero rows, a zero-row object with status PGRES_TUPLES_OK is
  25    returned; this is the signal that no more rows will arrive. (But note
  26    that it is still necessary to continue calling PQgetResult until it
  27    returns null.) All of these PGresult objects will contain the same row
  28    description data (column names, types, etc.) that an ordinary PGresult
  29    object for the query would have. Each object should be freed with
  30    PQclear as usual.
  31
  32    When using pipeline mode, single-row or chunked mode needs to be
  33    activated for each query in the pipeline before retrieving results for
  34    that query with PQgetResult. See Section 32.5 for more information.
  35
  36    PQsetSingleRowMode #
  37           Select single-row mode for the currently-executing query.
  38
  39 int PQsetSingleRowMode(PGconn *conn);
  40
  41           This function can only be called immediately after PQsendQuery
  42           or one of its sibling functions, before any other operation on
  43           the connection such as PQconsumeInput or PQgetResult. If called
  44           at the correct time, the function activates single-row mode for
  45           the current query and returns 1. Otherwise the mode stays
  46           unchanged and the function returns 0. In any case, the mode
  47           reverts to normal after completion of the current query.
  48
  49    PQsetChunkedRowsMode #
  50           Select chunked mode for the currently-executing query.
  51
  52 int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
  53
  54           This function is similar to PQsetSingleRowMode, except that it
  55           specifies retrieval of up to chunkSize rows per PGresult, not
  56           necessarily just one row. This function can only be called
  57           immediately after PQsendQuery or one of its sibling functions,
  58           before any other operation on the connection such as
  59           PQconsumeInput or PQgetResult. If called at the correct time,
  60           the function activates chunked mode for the current query and
  61           returns 1. Otherwise the mode stays unchanged and the function
  62           returns 0. In any case, the mode reverts to normal after
  63           completion of the current query.
  64
  65 Caution
  66
  67    While processing a query, the server may return some rows and then
  68    encounter an error, causing the query to be aborted. Ordinarily, libpq
  69    discards any such rows and reports only the error. But in single-row or
  70    chunked mode, some rows may have already been returned to the
  71    application. Hence, the application will see some PGRES_SINGLE_TUPLE or
  72    PGRES_TUPLES_CHUNK PGresult objects followed by a PGRES_FATAL_ERROR
  73    object. For proper transactional behavior, the application must be
  74    designed to discard or undo whatever has been done with the
  75    previously-processed rows, if the query ultimately fails.