MongoCursor
PHP Manual

MongoCursor::batchSize

(PECL mongo >=1.0.11)

MongoCursor::batchSizeひとつのバッチで返す要素数を制限する

説明

public MongoCursor MongoCursor::batchSize ( int $batchSize )

カーソルは一般的に、結果オブジェクトをバッチで取得してローカルに格納します。 このメソッドはバッチのサイズを決めるもので、 ひとつのデータパケットでサーバーから取得するドキュメントの数を設定できます。 しかし、バッチサイズの最大値 (通常は 4MB) に収まらないドキュメントは返せません。

パラメータ

batchSize

バッチで返す結果の数。バッチごとにサーバーとのやりとりが発生します。

batchSize2 以上 の場合は、取得するオブジェクトの各バッチのサイズを表します。 これをうまく調整すれば、パフォーマンスとデータ転送量を最適化できます。

batchSize1 あるいは負の数の場合は、 返すドキュメントの最大数を batchSize の絶対値までに抑え、 結果を返した後にカーソルを閉じます。 たとえば batchSize を -10 にすると、サーバーは 4MB に収まる範囲で最大 10 件までのドキュメントを返して カーソルを閉じます。

警告

batchSize1 あるいは -1 の場合は特別で、 このカーソルからは 1 件のドキュメントしか返せなくなります。

この機能が MongoCursor::limit() と違うところは、 ドキュメントが最大サイズに収まらなければいけないという点と、 カーソルを閉じるリクエストをサーバーに送らなくてもよいという点です。 カーソルをループしている間にもバッチサイズを変更でき、 その次にバッチを取得するときから新しい設定が反映されます。

これは、MongoDB がクライアントに返すデータ量の制限を上書きすることはできません。 つまり、たとえバッチサイズを 1,000,000,000 にしても、 MongoDB がバッチあたりで返す結果は 4-16MB にしかならないということです。

一貫性を維持するため、 MongoCursor::batchSize()MongoCursor::limit() のルールは多少込み入ったものになっていますが、 「期待通りに」動作します。そのルールとは、 ハードリミットがソフトリミットを上書きし、 MongoCursor::limit() のほうが MongoCursor::batchSize() より優先順位が高くなるということです。 その結果、どちらであってももう一方より小さく設定されているほうが優先されます。 以下の例を参照ください。

返り値

このカーソルを返します。

例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)
?>

参考

MongoDB コアドキュメントの » batchSize

変更履歴

バージョン 説明
1.4.5

1.4.5 より前のバージョンでは、このメソッドは、 カーソルの反復処理が始まっている場合に MongoCursorException をスローしていました。


MongoCursor
PHP Manual