32.6. 分块检索查询结果 #
通常，libpq 会收集一条 SQL 命令的完整结果，并将其作为单个 PGresult 返回给应用程序。对于返回大量行的命令，这可能并不适用。对于这类情况，应用程序可以将 PQsendQuery 和 PQgetResult 用于单行模式或分块模式。在这些模式下，结果行会在从服务器收到时立即返回给应用程序；单行模式每次返回一行，分块模式则每次返回一组行。
要进入这些模式之一，请在成功调用 PQsendQuery（或其同类函数）后立即调用 PQsetSingleRowMode 或 PQsetChunkedRowsMode。这种模式选择只对当前正在执行的查询生效。然后按第 32.4 节所述，反复调用 PQgetResult 直到其返回空指针。如果查询返回了任何行，这些行会作为一个或多个 PGresult 对象返回。它们看起来与普通查询结果相同，只是状态码在单行模式下为 PGRES_SINGLE_TUPLE，在分块模式下为 PGRES_TUPLES_CHUNK，而不是 PGRES_TUPLES_OK。每个 PGRES_SINGLE_TUPLE 对象恰好包含一行结果，而 PGRES_TUPLES_CHUNK 对象至少包含一行、至多包含指定的每块行数。最后一行之后，会返回一个状态为 PGRES_TUPLES_OK 且不含行的对象；如果查询返回零行，则立即返回该对象。这表示不会再有更多行到达。（但请注意，仍然必须继续调用 PQgetResult 直到其返回空指针。）所有这些 PGresult 对象都会包含与该查询的普通 PGresult 对象相同的行描述数据（列名、类型等）。每个对象在使用完之后都应像往常一样通过 PQclear 释放。
在使用管道模式时，必须在用 PQgetResult 提取该查询结果之前，为管道中的每个查询分别激活单行模式或分块模式。更多信息见第 32.5 节。
PQsetSingleRowMode#为当前正在执行的查询选择单行模式。
int PQsetSingleRowMode(PGconn *conn);
此函数只能在调用
PQsendQuery或其某个同类函数之后立即调用，并且必须在该连接上执行任何其他操作之前调用，例如PQconsumeInput或PQgetResult。如果调用时机正确，该函数会为当前查询激活单行模式并返回 1；否则模式保持不变并返回 0。无论如何，当前查询结束后都会恢复为普通模式。PQsetChunkedRowsMode#为当前正在执行的查询选择分块模式。
int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);
该函数与
PQsetSingleRowMode类似，不同之处在于它指定每个PGresult最多返回chunkSize行，而不一定只返回一行。此函数也只能在调用PQsendQuery或其某个同类函数之后立即调用，并且必须在该连接上执行任何其他操作之前调用，例如PQconsumeInput或PQgetResult。如果调用时机正确，该函数会为当前查询激活分块模式并返回 1；否则模式保持不变并返回 0。无论如何，当前查询结束后都会恢复为普通模式。
小心
在处理一个查询的过程中，服务器可能先返回一些行，然后遇到错误并中止该查询。通常，libpq 会丢弃这些行，只报告错误。但在单行模式或分块模式下，部分行可能已经返回给应用程序。因此，应用程序可能会先看到一些 PGRES_SINGLE_TUPLE 或 PGRES_TUPLES_CHUNK 的 PGresult 对象，然后再看到一个 PGRES_FATAL_ERROR 对象。为了获得正确的事务语义，如果查询最终失败，应用程序必须能丢弃或撤销之前对这些已处理行所做的操作。