getMore.txt

.. _manual-reference-commands-getMore:

=======
getMore
=======

.. default-domain:: mongodb

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

Definition
----------

.. dbcommand:: getMore

   Use in conjunction with commands that return a cursor. For example,
   :dbcommand:`find` and :dbcommand:`aggregate`, to return subsequent
   batches of documents currently pointed to by the cursor.

Compatibility
-------------

This command is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst
   
Syntax
------

The command has the following syntax:

.. code-block:: javascript

   db.runCommand(
      {
         getMore: <long>,
         collection: <string>,
         batchSize: <int>,
         maxTimeMS: <int>,
         comment: <any>
      }
   )

Command Fields
--------------

The command accepts the following fields:

.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Field
     - Type
     - Description

   * - ``getMore``
     - long
     - The cursor identifier.

   * - ``collection``
     - string
     - The name of the collection over which the cursor is operating.
       
   * - ``batchSize``
     - positive integer
     - Optional. Specifies the maximum number of documents within each batch returned in a query result.

       If batchSize is not set, getMore returns up to ``101`` documents in the first batch 
       and up to 16 mebibytes (MiB) of data in all subsequent batches. If ``batchSize`` is set, ``getMore`` returns
       the smaller of 16 mebibytes of data or ``batchSize`` documents. If you set ``batchSize`` to a limit that results 
       in batches larger than 16 MiB, this option has no effect.

   * - ``maxTimeMS``
     - non-negative integer
     - Optional. 

       Specifies the maximum time for the server to wait for new documents
       that match a :ref:`tailable cursor <tailable-cursors-landing-page>`
       query on a :ref:`capped collection <manual-capped-collection>`. 
       ``maxTimeMS`` on a ``getMore`` for a tailable ``awaitData`` cursor is 
       considered the same as :method:`~cursor.maxAwaitTimeMS()`.
       Drivers will only set this value on ``getMore`` for a tailable 
       cursor on a capped collection with ``awaitData`` set to ``true``. Otherwise, 
       the command that creates the cursor sets ``maxTimeMS``, which 
       is the maximum amount of time that the initial operation, and 
       any subsequent ``getMore`` operations, can spend cumulatively executing 
       the query. For tailable cursors with ``awaitData`` set to ``true``, 
       the following is true:
       
       - If no value is provided, the wait time defaults to ``1`` (1000 milliseconds).
       - ``maxTimeMS`` on ``getMore`` specifies the maximum amount of time 
         MongoDB waits for new documents to be inserted into the capped 
         collection for that specific ``getMore`` command. 
       - ``maxTimeMS`` is set individually by the driver for each call to ``getMore``.     

       MongoDB terminates operations that exceed their allotted time limit
       using the same mechanism as :method:`db.killOp()`. MongoDB only
       terminates an operation at one of its designated :term:`interrupt points <interrupt point>`.

       - You cannot set ``maxTimeMS`` when calling ``getMore`` on a
         non-tailable cursor. Instead, set it using
         :method:`~cursor.maxTimeMS()` when you create the cursor.
       - To use ``getMore`` with ``maxTimeMS`` on a tailable cursor, 
         enable ``awaitData`` when you create the cursor using :method:`cursor.tailable()`.
       - Setting ``maxTimeMS`` on the command that creates a cursor only
         sets the time limit for that operation. Use ``getMore`` to set
         a limit on further operations.
       - You can set or omit ``maxTimeMS`` for each call to 
         ``getMore``, and you don't have to use the same value.
       - For a tailable cursor, a timeout on ``getMore`` retains the
         documents accumulated before the timeout occurred in the
         cursor. For a non-tailable cursor, a timeout raises an error.
       

   * - ``comment``
     - any
     - .. include:: /includes/extracts/comment-content.rst

       If omitted, ``getMore`` inherits any ``comment`` set on the
       originating :dbcommand:`find` or :dbcommand:`aggregate` command.

Output
------

The command returns a document that contains the cursor information
as well as the next batch. 

For example, running ``getMore`` on a cursor created by a 
:dbcommand:`find` operation on a sharded cluster returns a document 
similar to this output:

.. code-block:: javascript
   :copyable: false

   {
      "cursor" : {
         "id" : NumberLong("678960441858272731"),
         "ns" : "test.contacts",
         "nextBatch" : [
            {
               "_id" : ObjectId("5e8e501e1a32d227f9085857"),
               "zipcode" : "220000"
            }
         ],
         "partialResultsReturned" : true,
         "postBatchResumeToken": "< Resume Token >"
      },
      "ok" : 1,
      "operationTime" : Timestamp(1586385239, 2),
      "$clusterTime" : {
         "clusterTime" : Timestamp(1586385239, 2),
         "signature" : {
            "hash" : BinData(0,"lLjejeW6AQGReR9x1PD8xU+tP+A="),
            "keyId" : NumberLong("6813467763969884181")
         }
      }
   }

.. list-table::
   :widths: 20 80
   :header-rows: 1
   
   * - Field
     - Description

   * - ``cursor``
     
     - Contains the cursor information, including the
       cursor ID as well as the ``nextBatch`` of documents.

       .. include:: /includes/find-getmore-partialresults.rst

       The ``postBatchResumeToken`` field can be used with the
       :pipeline:`$changeStream` pipeline to start or resume
       a change stream from this point.

   * - ``"ok"``
   
     - Indicates whether the command has succeeded (``1``) or failed
       (``0``).

In addition to these fields, the :method:`db.runCommand()` response
includes the following information for replica sets and sharded 
clusters:

- ``$clusterTime``
  
- ``operationTime``

See :ref:`db.runCommand() Response <command-response>` for details.


Behavior
--------

Access Control
~~~~~~~~~~~~~~

If :ref:`authentication <authentication>` is enabled, you can 
only run ``getMore`` against cursors you created.

Sessions
~~~~~~~~

For cursors created inside a session, you cannot call
``getMore`` outside the session.

Similarly, for cursors created outside of a session, you cannot call
``getMore`` inside a session.

Transactions
````````````

For :ref:`multi-document transactions <transactions>`:

.. include:: /includes/extracts/transactions-operations-getMore.rst

Slow Queries
~~~~~~~~~~~~

.. include:: /includes/getMore-slow-queries.rst

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

- :ref:`cursor-batchSize`
- :ref:`read-operations-cursors`