diff --git a/source/reference/method/cursor.batchSize.txt b/source/reference/method/cursor.batchSize.txt index 82d8dc7ac33..8c0e3c0af99 100644 --- a/source/reference/method/cursor.batchSize.txt +++ b/source/reference/method/cursor.batchSize.txt @@ -7,45 +7,33 @@ cursor.batchSize() .. method:: cursor.batchSize() The :method:`batchSize() ` method specifies the - number of documents the cursor will return in each batch. In most - cases, the effect of configuring the batch size will not affect the - user or application. + number of documents to return in each batch; MongoDB server returns + query results in batches. In most cases, the effect of configuring + the batch size will not affect the user or the application since the + :program:`mongo` shell and most driver present the results + seamlessly as though returned in a single batch. The :method:`batchSize() ` method takes the following parameter: :param size: - The number of documents to return per batch. This value - also affects whether to close the cursor after the first - batch. Refer to the specific driver ``batchSize`` - documentation for the cursor behavior as determined by the - ``size``. + The number of documents to return per batch. Do **not** use a + batch size of ``1``. - The :program:`mongo` shell will iterate over 20 documents - regardless of the configured batch size, unless you specify a - negative batch size. + .. note:: + + Specifying ``1`` or a negative number is analogous to using the + :method:`limit() ` method. Consider the following examples that use the :method:`batchSize() ` method in the :program:`mongo` shell: - - Set the number of documents returned by the :method:`find() - ` method to ``10`` per each batch: + - Set the batch size so that the results of the :method:`find()` are + returned in batches of ``10``. The effects of the batch size is + not visible to the user as the :program:`mongo` shell iterate over + the first 20 documents: .. code-block:: javascript - var curs = db.animals.find().batchSize(10) - - The cursor remains open so that you can iterate through the cursor - ``curs`` to access all documents in the ``animals`` collection. - - - Set the number of documents returned by the :method:`find() - ` method to ``10`` per each batch and close - after the first batch: - - .. code-block:: javascript - - var curs = db.animals.find().batchSize(-10) - - In the :program:`mongo` shell, the cursor closes after the first - batch so that you can iterate the cursor only ``10`` times. + db.animals.find().batchSize(10)