他のバージョンの文書 17 | 16 | 15 | 14 | 13 | 12 | 11 | 10 | 9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

32.6. 問い合わせ結果をチャンクとして取り出す #

通常、libpqはSQLコマンドの結果全体を収集し、それを1つのPGresultとしてアプリケーションに返します。 これは、多くの行数を返すコマンドでは動作しなくなるかもしれません。 このような場合、アプリケーションはPQsendQueryPQgetResult単一行モードまたはチャンクモードを使用することができます。 これらのモードでは、結果の行は、サーバから受信されると、一度に1行ずつ、またはチャンクでグループ化されてアプリケーションに返されます。

これらのモードのいずれかに入るには、PQsendQuery (またはその兄弟関数)の呼び出し直後にPQsetSingleRowModeまたはPQsetChunkedRowsModeを呼び出します。 このモード選択は、現在実行中の問い合わせに対してのみ有効です。 その後、32.4の説明通りに、NULLを返すようになるまでPQgetResultを繰り返し呼び出してください。 問い合わせが何らかの行を返す場合、PGRES_TUPLES_OKではなくPGRES_SINGLE_TUPLEである点を除けば、通常の問い合わせ結果と同じように見える、個々のPGresultオブジェクトを返します。 問い合わせが何行かの行を返すと、それらは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で解放する必要があります。

パイプラインモードを使用する場合、単一行モードまたはチャンクモードは、PQgetResultでその問い合わせの結果を取得する前に、パイプラインの各問い合わせに対してアクティブにする必要があります。 詳細は32.5を参照してください。

PQsetSingleRowMode #

現在実行中の問い合わせについて単一行モードを選択します。

int PQsetSingleRowMode(PGconn *conn);

この関数はPQsendQueryまたはその系列の関数のいずれかの後即座に、PQconsumeInput PQgetResultなど接続に対する何らかの他の操作を行う前のみに呼び出すことができます。 正しい時点で呼び出された場合、この関数は現在の問い合わせに対して単一行モードを有効にし、1を返します。 この他の場合、モードは変更されず、関数はゼロを返します。 いずれの場合でも、現在の問い合わせが完了した後に通常モードに戻ります。

PQsetChunkedRowsMode #

現在実行中の問い合わせに対してチャンクモードを選択します。

int PQsetChunkedRowsMode(PGconn *conn, int chunkSize);

この関数はPQsetSingleRowModeと似ていますが、必ずしも1行だけではなく、PGresultごとに最大chunkSize行を取得する点が異なります。 この関数は、PQsendQueryまたはその兄弟関数の直後、およびPQconsumeInput PQgetResultなどの接続上の他の操作の直前にのみ呼び出すことができます。 正しいタイミングで呼び出されると、この関数は現在の問い合わせに対してチャンクモードをアクティブにし、1を返します。 それ以外の場合、モードは変更されず、この関数は0を返します。 いずれの場合も、現在の問い合わせが完了すると、モードは通常に戻ります。

注意

問い合わせを処理している間、サーバはいくつか行を返した後にエラーになり、問い合わせがアボートする可能性があります。 通常のlibpqでは、こうした行を破棄しエラーのみを報告します。 しかし単一行モードあるいはチャンクモードでは、これらの行はすでにアプリケーションに返されています。 このためアプリケーションはPGRES_SINGLE_TUPLEあるいはPGRES_TUPLES_CHUNK状態のPGresultオブジェクトをいくつか見た後にPGRES_FATAL_ERRORオブジェクトを見るかもしれません。 適切な振る舞いのトランザクションのために、最終的に問い合わせが失敗した場合、アプリケーションはこれまで処理した行を破棄するまたは取り消すように設計しなければなりません。