merge: DOCS-579

Author: Sam Kleinman

source/reference/method/cursor.batchSize.txt

@@ -0,0 +1,53 @@
+==================
+cursor.batchSize()
+==================
+
+.. default-domain:: mongodb
+
+.. method:: cursor.batchSize()
+
+   The :method:`batchSize() <cursor.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() <cursor.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()
+   <cursor.batchSize()>` method in the :program:`mongo` shell:
+   
+   - Set the number of documents returned by the :method:`find()
+     <db.collection.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()
+     <db.collection.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.