diff --git a/source/reference/method/cursor.batchSize.txt b/source/reference/method/cursor.batchSize.txt new file mode 100644 index 00000000000..12cca244163 --- /dev/null +++ b/source/reference/method/cursor.batchSize.txt @@ -0,0 +1,53 @@ +================== +cursor.batchSize() +================== + +.. default-domain:: mongodb + +.. method:: cursor.batchSize() + + The :method:`batchSize() ` method specifies the + number of documents the cursor returns per batch. Specifying the + batchSize is a low-level optimization whose effects are not visible + to the user. + + The :method:`batchSize() ` method takes the + following parameter: + + :param size: + + The number of documents to return per batch. The ``size`` + 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``. + + .. note:: + + The actual number of documents in the batch may be smaller as + determined by the limit or the 4 megabyte size limit of the + server reply. + + Consider the following examples of 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: + + .. 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.