parallelCollectionScan

On this page

  • parallelCollectionScan
    • New in version 2.6.

Allows applications to use multiple parallel cursors when reading all the documents from a collection, thereby increasing throughput. The parallelCollectionScan command returns a document that contains an array of cursor information.

Each cursor provides access to the return of a partial set of documents from a collection. Iterating each cursor returns every document in the collection. Cursors do not contain the results of the database command. The result of the database command identifies the cursors, but does not contain or constitute the cursors.

Important

  • The server may return fewer cursors than requested.

  • This command will not return more than one cursor for the WiredTiger storage engine.

The command has the following syntax:

{
  parallelCollectionScan: "<collection>",
  numCursors: <integer>,
  readConcern: <document>,
  maxTimeMS: <integer>
}

The parallelCollectionScan command takes the following fields:

FieldTypeDescription
parallelCollectionScanstringThe name of the collection.
numCursorsintegerThe maximum number of cursors to return. Must be between 1 and 10000, inclusive.
readConcerndocumentOptional. Specifies the read concern.
The readConcern option has the following syntax:
Changed in version 3.6.
readConcern: { level: <value> }
Possible read concern levels are:
"local". This is the default read concern level.
"available". This is the default for reads against secondaries when Read Operations and Causally Consistent Sessions and “level” are unspecified. The query returns the instance’s most recent data.
"majority". Available for replica sets that use WiredTiger storage engine.
"linearizable". Available for read operations on the primary only.
For more formation on the read concern levels, see Read Concern Levels.
For "local" (default) or "majority" read concern level, you can specify the afterClusterTime option to have the read operation return data that meets the level requirement and the specified after cluster time requirement. For more information, see Read Operations and Causally Consistent Sessions.
maxTimeMSnon-negative integerOptional. 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.

parallelCollectionScan is only available for mongod, and it cannot operate on a sharded cluster.

Example

Override Default Read Concern

To override the default read concern level of "local", use the readConcern option.

The following operation on a replica set specifies a Read Concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

Note

Starting in MongoDB 3.6, support for read concern "majority" is enabled by default. For MongoDB 3.6.1 - 3.6.x, you can disable read concern "majority". For more information, see Disable Read Concern Majority.

  • Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.
db.runCommand(
   {
      parallelCollectionScan: "restaurants",
      numCursors: 5,
      readConcern: { level: "majority" }
   }
)

To ensure that a single thread can read its own writes, use "majority" read concern and "majority" write concern against the primary of the replica set.

Output

The parallelCollectionScan command returns a document containing the array of cursor information:

{
    "cursors" : [
        {
            "cursor" : {
                "firstBatch" : [ ],
                "ns" : "<database name>.<collection name>",
                "id" : NumberLong("155949257847")
            },
            "ok" : true
        }
    ],
    "ok" : 1
}
  • parallelCollectionScan. cursors

    • An array with one or more cursors returned with the command.
  • parallelCollectionScan.cursors. cursor

    • For each cursor returned, a document with details about the cursor.
  • parallelCollectionScan.cursors.cursor. firstBatch

    • An empty first batch is useful for quickly returning a cursor or failure message without doing significant server-side work. See cursor batches.
  • parallelCollectionScan.cursors.cursor. ns

    • The namespace for each cursor.
  • parallelCollectionScan.cursors.cursor. id

    • The unique id for each cursor.
  • parallelCollectionScan.cursors. ok

    • The status of each cursor returned with the command.
  • parallelCollectionScan. ok