cursor.batchSize.txt

.. _cursor-batchSize:

==================
cursor.batchSize()
==================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: cursor.batchSize(size)

   .. include:: /includes/fact-mongosh-shell-method.rst

   Specifies the
   number of documents to return in each batch of the response from the
   MongoDB instance. In most cases, modifying the batch size will
   not affect the user or the application, as :binary:`~bin.mongosh` and
   most :driver:`drivers </>` return results as if MongoDB returned a
   single batch.

   .. note::

      If the batch size is too large, the cursor allocates more
      resources than it requires, which can negatively impact
      query performance.  If the batch size is too small, the
      cursor requires more network round trips to retrieve the
      query results, which can negatively impact query
      performance.

      Adjust ``batchSize`` to a value appropriate to your
      database, load, and application needs.

   The :method:`~cursor.batchSize()` method takes the
   following field:

   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Field
        - Type
        - Description
   
      * - ``size``
        - integer
        - The initial number of documents to return for a batch. The
          default initial batch size is 101 documents. Subsequent
          batches are 16 megabytes. The default applies to drivers and
          Mongo Shell. For details, see :ref:`cursor-batches`.

Example
-------

The following example sets ``batchSize`` for the results of a query
(specifically, :method:`~db.collection.find()`) to ``10``:

.. code-block:: javascript

   db.inventory.find().batchSize(10)

Learn More
----------

- :ref:`cursor-batches`
- :method:`cursor.next()`
- :dbcommand:`getMore`