MongoCursor::batchSize

(PECL mongo >=1.0.11)

MongoCursor::batchSize — Sets the number of results returned per result set

Description

public MongoCursor MongoCursor::batchSize ( int $num )

This cannot override MongoDB's limit on the amount of data it will return to the client (i.e., if you set batch size to 1,000,000,000, MongoDB will still only return 4-16MB of results).

To ensure consistent behavior, the rules of batchSize and limit behavior a little complex but work "as expected". The rules are: hard limits override soft limits with preference given to MongoCursor::limit() over MongoCursor::batchSize(). After that, whichever is set and lower than the other will take precedence. Some examples:


<?php

// one batch, at most 20 items
$cursor->limit(-20)->batchSize(10);

// one batch, at most 10 items
$cursor->limit(20)->batchSize(-10);

// first batch: at most 10 items
$cursor->limit(10);

// first batch: at most 10 items
$cursor->limit(10)->batchSize(20);

// first batch: at most 10 items
$cursor->limit(20)->batchSize(10);


$cursor->limit(30)->batchSize(7)
// if we iterate through 28 items, the next call to getNext() will contact the 
// database and request a batch of 2 documents

?>

Parameters

num: The number of results to return in the next batch.

Return Values

Returns this cursor.

Errors/Exceptions

Throws MongoCursorException if this cursor has started iterating. This will change in 1.0.12, as this should be able to be called at any time.