(PECL mongo >=1.0.11)
MongoCursor::batchSize — ひとつのバッチで返す要素数を制限する
カーソルは一般的に、結果オブジェクトをバッチで取得してローカルに格納します。 このメソッドはバッチのサイズを決めるもので、 ひとつのデータパケットでサーバーから取得するドキュメントの数を設定できます。 しかし、バッチサイズの最大値 (通常は 4MB) に収まらないドキュメントは返せません。
batchSize
バッチで返す結果の数。バッチごとにサーバーとのやりとりが発生します。
batchSize が 2 以上
の場合は、取得するオブジェクトの各バッチのサイズを表します。
これをうまく調整すれば、パフォーマンスとデータ転送量を最適化できます。
batchSize が 1 あるいは負の数の場合は、
返すドキュメントの最大数を batchSize の絶対値までに抑え、
結果を返した後にカーソルを閉じます。
たとえば batchSize を -10
にすると、サーバーは 4MB に収まる範囲で最大 10 件までのドキュメントを返して
カーソルを閉じます。
batchSize が 1
あるいは -1 の場合は特別で、
このカーソルからは 1 件のドキュメントしか返せなくなります。
この機能が MongoCursor::limit() と違うところは、 ドキュメントが最大サイズに収まらなければいけないという点と、 カーソルを閉じるリクエストをサーバーに送らなくてもよいという点です。 カーソルをループしている間にもバッチサイズを変更でき、 その次にバッチを取得するときから新しい設定が反映されます。
これは、MongoDB がクライアントに返すデータ量の制限を上書きすることはできません。 つまり、たとえバッチサイズを 1,000,000,000 にしても、 MongoDB がバッチあたりで返す結果は 4-16MB にしかならないということです。
一貫性を維持するため、 MongoCursor::batchSize() と MongoCursor::limit() のルールは多少込み入ったものになっていますが、 「期待通りに」動作します。そのルールとは、 ハードリミットがソフトリミットを上書きし、 MongoCursor::limit() のほうが MongoCursor::batchSize() より優先順位が高くなるということです。 その結果、どちらであってももう一方より小さく設定されているほうが優先されます。 以下の例を参照ください。
このカーソルを返します。
このカーソルの反復処理が始まっている場合に MongoCursorException をスローします。
例1 MongoCursor::batchSize() を MongoCursor::limit() と組み合わせる例
<?php
// ひとつのバッチで最大 10 件。-10 でサーバーから 10 件を返し、
// カーソルを削除する。
$cursor->limit(20)->batchSize(-10);
// 最初のバッチ。最大 10 件
$cursor->limit(10);
// 最初のバッチ。最大 10 件
$cursor->limit(10)->batchSize(20);
// 結果を 10 件ずつのバッチで取得し、最大で 20 件
// (10 件のバッチが二つ) を返す
$cursor->limit(20)->batchSize(10);
// 結果を 7 件ずつのバッチで取得し、最大で 30 件を返す
// (ドライバが 7 件のバッチを 4 回リクエストし、最後のバッチは 2 件となる)
$cursor->limit(30)->batchSize(7)
?>