From b2cfbc95b579db63e043fb19dedac65026f04b29 Mon Sep 17 00:00:00 2001 From: Derick Rethans Date: Wed, 25 Apr 2012 18:04:50 +0000 Subject: [PATCH] Properly document MongoCursor::batchSize(). (PHP-284) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@325451 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mongo/mongocursor/batchsize.xml | 140 +++++++++++++++------- reference/mongo/mongocursor/limit.xml | 5 + 2 files changed, 102 insertions(+), 43 deletions(-) diff --git a/reference/mongo/mongocursor/batchsize.xml b/reference/mongo/mongocursor/batchsize.xml index ac8755cba4..2d13781752 100644 --- a/reference/mongo/mongocursor/batchsize.xml +++ b/reference/mongo/mongocursor/batchsize.xml @@ -4,54 +4,22 @@ MongoCursor::batchSize - Sets the number of results returned per result set + Limits the number of elements returned in one batch. &reftitle.description; public MongoCursorMongoCursor::batchSize - intnum + intbatchSize - 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). + A cursor typically fetches a batch of result objects and store them + locally. This method sets the batchSize value to configure the amount of + documents retrieved from the server in one data packet. However, it will + never return more documents than fit in the max batch size limit (usually + 4MB). - - 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: - - -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 - -?> -]]> - @@ -60,11 +28,54 @@ $cursor->limit(30)->batchSize(7) - num + batchSize - The number of results to return in the next batch. + The number of results to return per batch. Each batch requires a + round-trip to the server. + + + If batchSize is 2 or + more, it represents the size of each batch of objects retrieved. + It can be adjusted to optimize performance and limit data transfer. + + + If batchSize is 1 or negative, it + will limit of number returned documents to the absolute value of batchSize, + and the cursor will be closed. For example if + batchSize is -10, then the server will return a maximum + of 10 documents and as many as can fit in 4MB, then close the cursor. + + + + A batchSize of 1 is special, and + means the same as -1, i.e. a value of + 1 makes the cursor only capable of returning + one document. + + + + Note that this feature is different from + MongoCursor::limit in that documents must fit within a + maximum size, and it removes the need to send a request to close the cursor + server-side. The batch size can be changed even after a cursor is iterated, + in which case the setting will apply on the next batch retrieval. + + + 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 per batch). + + + To ensure consistent behavior, the rules of + MongoCursor::batchSize and + MongoCursor::limit behave 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. See below. + section for some examples. @@ -83,11 +94,54 @@ $cursor->limit(30)->batchSize(7) &reftitle.errors; 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. + started iterating. + + &reftitle.examples; + + <function>Mongo::batchSize</function> and combinations with + <function>MongoCursor::limit</function> + +limit(20)->batchSize(-10); + +// first batch: at most 10 items +$cursor->limit(10); + +// first batch: at most 10 items +$cursor->limit(10)->batchSize(20); + +// results are fetched in batches of 10 each, with a maximum of 20 items +// returned (that means two batches of 10). +$cursor->limit(20)->batchSize(10); + +// results are fetched in batches of 7 each, with a maximum of 30 items +// returned (that means that the driver requests 4 batches of 7, and one batch +// of 2). +$cursor->limit(30)->batchSize(7) +?> +]]> + + + + + + &reftitle.seealso; + + MongoDB core docs on limit. + + + + MongoCursor::limit + + +