Docs Menu

Docs Home → Develop Applications → MongoDB Manual

getMore

On this page

  • Definition
  • Syntax
  • Command Fields
  • Output
  • Behavior

Definition

getMore

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

Syntax

The command has the following syntax:

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 id.
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.
maxTimeMS
non-negative integer

Optional.

Specifies a time limit in milliseconds for processing operations on a cursor. If you do not specify a value for maxTimeMS, operations will not time out. A value of 0 explicitly specifies the default unbounded behavior.

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.

With tailable cursors:

  • maxTimeMS on getMore specifies the maximum amount of time MongoDB waits for new documents to be added to the cursor for that specific getMore command. If no value is provided, this defaults to 1000 milliseconds.

  • The command that creates the cursor only sets maxTimeMS for the initial operation. It does not set maxTimeMS for subsequent operations.

  • Set maxTimeMS individually for each call to getMore.

  • A timeout on getMore will retain the documents accumulated before the timeout occurred in the cursor.

With non-tailable cursors:

  • The command that creates the cursor sets maxTimeMS. This is the maximum amount of time that the initial operation, and any subsequent operations, can spend on the entire cursor.

  • A timeout on getMore raises an error.

  • maxTimeMS cannot be set when getMore is called on a non-tailable cursor.

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.

New in version 4.4.

Output

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

For example, a document similar to the one below may be returned when getMore is run on a cursor that was originally created by a find operation on a sharded cluster:

{
   "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.

Starting in 4.4, if the cursor from a find command returns partial results due to the unavailability of the queried shard(s), the cursor document includes a partialResultsReturned field. To return partial results, rather than error, due to the unavailability of the queried shard(s), the initial find command must run with allowPartialResults set to true. See allowPartialResults.

If the queried shards are initially available for the find command but one or more shards become unavailable in subsequent getMore commands, only the getMore commands run when a queried shard or shards are unavailable include the partialResultsReturned flag in the 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 the aforementioned getMore-specific fields, the db.runCommand() includes the following information for replica sets and sharded clusters:

  • $clusterTime

  • operationTime

See db.runCommand() Results for details.

Behavior

Access Control

If authentication is turned on, you can only issue a getMore against cursors you created.

Sessions

New in version 4.0.

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

New in version 4.0.

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.

Slow Queries

Starting in MongoDB 5.1, when a getMore command is logged as a slow query, the queryHash and planCacheKey fields are added to the slow query log message and the profiler log message.

←  getLastErrorinsert →

On this page