Docs Menu
Docs Home
/
MongoDB Manual
/
Reference
/
Database Commands
/
Query and Write Operation Commands

getMore

On this page

  • Definition
  • Syntax
  • Behavior

Definition

getMore

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

Syntax

The getMore command has the following form:

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

Command Fields

The command accepts the following fields:

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. The number of documents to return in the batch.

If batchSize is not set, getMore returns up to 16 megabytes of data. If batchSize is set, getMore returns the smaller of 16 megabytes of data or batchSize documents.

maxTimeMS
non-negative integer

Optional.

Specifies the maximum time for the server to wait for new documents that match a tailable cursor query on a capped collection. 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 db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

  • You cannot set maxTimeMS when calling getMore on a non-tailable cursor. Instead, set it using maxTimeMS() when you create the cursor.

  • To use getMore with maxTimeMS on a tailable cursor, enable awaitData when you create the cursor using 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

Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:

A comment can be any valid BSON type (string, integer, object, array, etc).

Note

If omitted, getMore inherits any comment set on the originating find or 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 find operation on a sharded cluster returns a document similar to this output:

{
   "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")
      }
   }
}
Field
Description
cursor

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

If find (or subsequent getMore commands) returns partial results because the queried shard(s) aren't available, the find output includes a partialResultsReturned indicator field. If the queried shards are available for the initial find command, but one or more shards become unavailable for subsequent getMore commands, only the getMore commands that run while the shards aren't available include partialResultsReturned in their output.

The postBatchResumeToken field can be used with the $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 db.runCommand() response includes the following information for replica sets and sharded clusters:

  • $clusterTime

  • operationTime

See db.runCommand() Response for details.

Behavior

Access Control

If 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 multi-document transactions:

  • For cursors created outside of a transaction, you cannot call getMore inside the transaction.

  • For cursors created in a transaction, you cannot call getMore outside the transaction.

Back

getLastError

Next

insert