バージョンごとのドキュメント一覧

32.6. Retrieving Query Results in Chunks #

Ordinarily, <application>libpq</application> collects an SQL command's entire result and returns it to the application as a single <structname>PGresult</structname>. This can be unworkable for commands that return a large number of rows. For such cases, applications can use <xref linkend="libpq-PQsendQuery"/> and <xref linkend="libpq-PQgetResult"/> in <firstterm>single-row mode</firstterm> or <firstterm>chunked mode</firstterm>. In these modes, result row(s) are returned to the application as they are received from the server, one at a time for single-row mode or in groups for chunked mode. 《マッチ度[76.381910]》通常、libpqはSQLコマンドの結果全体を収集し、それを1つのPGresultとしてアプリケーションに返します。 これは、多くの行数を返すコマンドでは動作しなくなるかもしれません。 こうした場合、アプリケーションはPQsendQueryPQgetResult単一行モードで使用することができます。 このモードでは、結果行は、サーバから受け取ったかのように、アプリケーションに1度に1行返されます。 《機械翻訳》通常、libpqはSQLコマンドの結果全体を収集し、それを単一のPGresultとしてアプリケーションに返します。 これは、多数の行を返すコマンドには使用できません。 このような場合、アプリケーションはシングルローモードまたはチャンクモードPQsendQueryPQgetResultを使用することができます。 これらのモードでは、結果の行は、サーバから受信されると、一度に1行ずつ、またはチャンクでグループ化されてアプリケーションに返されます。

To enter one of these modes, call <xref linkend="libpq-PQsetSingleRowMode"/> or <xref linkend="libpq-PQsetChunkedRowsMode"/> immediately after a successful call of <xref linkend="libpq-PQsendQuery"/> (or a sibling function). This mode selection is effective only for the currently executing query. Then call <xref linkend="libpq-PQgetResult"/> repeatedly, until it returns null, as documented in <xref linkend="libpq-async"/>. If the query returns any rows, they are returned as one or more <structname>PGresult</structname> objects, which look like normal query results except for having status code <literal>PGRES_SINGLE_TUPLE</literal> for single-row mode or <literal>PGRES_TUPLES_CHUNK</literal> for chunked mode, instead of <literal>PGRES_TUPLES_OK</literal>. There is exactly one result row in each <literal>PGRES_SINGLE_TUPLE</literal> object, while a <literal>PGRES_TUPLES_CHUNK</literal> object contains at least one row but not more than the specified number of rows per chunk. After the last row, or immediately if the query returns zero rows, a zero-row object with status <literal>PGRES_TUPLES_OK</literal> is returned; this is the signal that no more rows will arrive. (But note that it is still necessary to continue calling <xref linkend="libpq-PQgetResult"/> until it returns null.) All of these <structname>PGresult</structname> objects will contain the same row description data (column names, types, etc.) that an ordinary <structname>PGresult</structname> object for the query would have. Each object should be freed with <xref linkend="libpq-PQclear"/> as usual. 《マッチ度[73.358586]》単一行モードに入るためには、PQsendQuery(または同系列の関数)の呼び出しに成功した直後にPQsetSingleRowModeを呼び出してください。 このモード選択は、現在実行中の問い合わせに対してのみ有効です。 その後、32.4の説明通りに、NULLを返すようになるまでPQgetResultを繰り返し呼び出してください。 問い合わせが何らかの行を返す場合、PGRES_TUPLES_OKではなくPGRES_SINGLE_TUPLEである点を除けば、通常の問い合わせ結果と同じように見える、個々のPGresultオブジェクトを返します。 最後の行の後、または問い合わせがゼロ行を返す場合は即座に、PGRES_TUPLES_OK状態のゼロ行のオブジェクトが返されます。 これはもう行が届かないことを通知するものです。 (しかしNULLが返るまでPQgetResultを呼び出さなければならないことに注意してください。) PGresultオブジェクトのすべては、その問い合わせに対する通常のPGresultと同一の行説明データ(列名、型など)を持ちます。 各オブジェクトは通常通りPQclearで解放しなければなりません。 《機械翻訳》これらのモードのいずれかに入るには、PQsendQuery (またはその兄弟関数) の呼び出し直後にPQsetSingleRowModeまたはPQsetChunkedRowsModeを呼び出します。 このモード選択は、現在実行中のクエリに対してのみ有効です。 次に、PQgetResult32.4で説明されているように、NULLが返されるまで繰り返し呼び出します。 問い合わせが何行かの行を返すと、それらは1つ以上のPGresultオブジェクトとして返されます。 これらは通常の問い合わせ結果と同じように見えますが、PGRES_SINGLE_TUPLEがシングル行モードの場合はPGRES_TUPLES_OKではなく、チャンクモードの場合はPGRES_TUPLES_CHUNKが付きます。 各PGRES_SINGLE_TUPLEオブジェクトには1行の結果がありますが、PGRES_TUPLES_CHUNKオブジェクトには少なくとも1行、チャンクあたり指定された行数以上の結果があります。 最後の行の後、またはクエリがゼロ行を返す場合は直ちに、ステータスPGRES_TUPLES_OKを持つゼロ行オブジェクトが返されます。 これは、これ以上行が到着しないというシグナルです。 (ただし、NULL を返すまでは、PQgetResultを呼び出し続ける必要があることに注意してください。) これらのPGresultオブジェクトはすべて、問い合わせの通常のPGresultオブジェクトと同じ行記述データ(列名、型など)を含みます。 各オブジェクトは通常通りPQclearで解放する必要があります。

When using pipeline mode, single-row or chunked mode needs to be activated for each query in the pipeline before retrieving results for that query with <function>PQgetResult</function>. See <xref linkend="libpq-pipeline-mode"/> for more information. 《マッチ度[90.763052]》パイプラインモードを使用する場合、単一行モードは、PQgetResultでその問い合わせの結果を取得する前に、パイプラインの各問い合わせに対してアクティブにする必要があります。 詳細は32.5を参照してください。

PQsetSingleRowMode #

Select single-row mode for the currently-executing query. 現在実行中の問い合わせについて単一行モードを選択します。

int PQsetSingleRowMode(PGconn *conn);

This function can only be called immediately after <xref linkend="libpq-PQsendQuery"/> or one of its sibling functions, before any other operation on the connection such as <xref linkend="libpq-PQconsumeInput"/> or <xref linkend="libpq-PQgetResult"/>. If called at the correct time, the function activates single-row mode for the current query and returns 1. Otherwise the mode stays unchanged and the function returns 0. In any case, the mode reverts to normal after completion of the current query. この関数はPQsendQueryまたはその系列の関数のいずれかの後即座に、PQconsumeInput PQgetResultなど接続に対する何らかの他の操作を行う前のみに呼び出すことができます。 正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。 この他の場合、モードは変更されず、関数はゼロを返します。 いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。

PQsetChunkedRowsMode #

Select chunked mode for the currently-executing query. 《マッチ度[70.370370]》現在実行中の問い合わせについて単一行モードを選択します。 《機械翻訳》現在実行中のクエリに対してチャンク・モードを選択します。

int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);

This function is similar to <xref linkend="libpq-PQsetSingleRowMode"/>, except that it specifies retrieval of up to <replaceable>chunkSize</replaceable> rows per <structname>PGresult</structname>, not necessarily just one row. This function can only be called immediately after <xref linkend="libpq-PQsendQuery"/> or one of its sibling functions, before any other operation on the connection such as <xref linkend="libpq-PQconsumeInput"/> or <xref linkend="libpq-PQgetResult"/>. If called at the correct time, the function activates chunked mode for the current query and returns 1. Otherwise the mode stays unchanged and the function returns 0. In any case, the mode reverts to normal after completion of the current query. 《マッチ度[60.220994]》この関数はPQsendQueryまたはその系列の関数のいずれかの後即座に、PQconsumeInput PQgetResultなど接続に対する何らかの他の操作を行う前のみに呼び出すことができます。 正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。 この他の場合、モードは変更されず、関数はゼロを返します。 いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。 《機械翻訳》この関数はPQsetSingleRowModeと似ていますが、PGresultごとに最大chunkSize行を取得する点が異なります。 必ずしも1行だけではありません。 この関数は、PQsendQueryまたはその兄弟関数の直後、およびPQconsumeInput PQgetResultなどの接続上の他の操作の直前にのみ呼び出すことができます。 正しい時間に呼び出されると、この関数は現在のクエリに対してチャンク・モードをアクティブにし、1を返します。 それ以外の場合、モードは変更されず、この関数は0を返します。 いずれの場合も、現在のクエリが完了すると、モードは通常に戻ります。

注意

While processing a query, the server may return some rows and then encounter an error, causing the query to be aborted. Ordinarily, <application>libpq</application> discards any such rows and reports only the error. But in single-row or chunked mode, some rows may have already been returned to the application. Hence, the application will see some <literal>PGRES_SINGLE_TUPLE</literal> or <literal>PGRES_TUPLES_CHUNK</literal> <structname>PGresult</structname> objects followed by a <literal>PGRES_FATAL_ERROR</literal> object. For proper transactional behavior, the application must be designed to discard or undo whatever has been done with the previously-processed rows, if the query ultimately fails. 《マッチ度[85.390071]》問い合わせを処理している間、サーバはいくつか行を返した後にエラーになり、問い合わせがアボートする可能性があります。 通常のlibpqでは、こうした行を破棄しエラーのみを報告します。 しかし単一行モードでは、これらの行はすでにアプリケーションに返されています。 このためアプリケーションはPGRES_SINGLE_TUPLE状態のPGresultオブジェクトをいくつか見た後にPGRES_FATAL_ERRORオブジェクトを見るかもしれません。 適切な振る舞いのトランザクションのために、最終的に問い合わせが失敗した場合、アプリケーションはこれまで処理した行を破棄するまたは取り消すように設計しなければなりません。 《機械翻訳》クエリの処理中に、サーバがいくつかの行を結果してからエラーに遭遇し、クエリが中断されることがあります。 通常、libpqはそのような行を破棄し、エラーのみを報告します。 しかし、単一行またはチャンクモードでは、一部の列がすでにアプリケーションに戻されている場合があります。 従って、アプリケーションはいくつかのPGRES_SINGLE_タプルまたはPGRES_TUPLES_チャンクPGresultオブジェクトとそれに続くPGRES_FATAL_エラーオブジェクトを見ることになります。 トランザクションが適切に動作するためには、アプリケーションが最終的に失敗した場合に、以前に処理された行に対して行われたことを破棄または元に戻すようにクエリを設計する必要があります。