Class: Cursor

Cursor

new Cursor(){Cursor}

Creates a new Cursor instance (INTERNAL TYPE, do not instantiate directly)

Properties:
Name Type Description
sortValue string

Cursor query sort setting.

timeout boolean

Is Cursor able to time out.

readPreference ReadPreference

Get cursor ReadPreference.

Fires:
Returns:
Cursor instance.
Example

Cursor cursor options.

collection.find({}).project({a:1}) // Create a projection of field a
collection.find({}).skip(1).limit(10) // Skip 1 and limit 10
collection.find({}).batchSize(5) // Set batchSize on cursor to 5
collection.find({}).filter({a:1}) // Set query on the cursor
collection.find({}).comment('add a comment') // Add a comment to the query, allowing to correlate queries
collection.find({}).addCursorFlag('tailable', true) // Set cursor as tailable
collection.find({}).addCursorFlag('noCursorTimeout', true) // Set cursor as noCursorTimeout
collection.find({}).addCursorFlag('awaitData', true) // Set cursor as awaitData
collection.find({}).addCursorFlag('partial', true) // Set cursor as partial
collection.find({}).addQueryModifier('$orderby', {a:1}) // Set $orderby {a:1}
collection.find({}).max(10) // Set the cursor max
collection.find({}).maxTimeMS(1000) // Set the cursor maxTimeMS
collection.find({}).min(100) // Set the cursor min
collection.find({}).returnKey(true) // Set the cursor returnKey
collection.find({}).setReadPreference(ReadPreference.PRIMARY) // Set the cursor readPreference
collection.find({}).showRecordId(true) // Set the cursor showRecordId
collection.find({}).sort([['a', 1]]) // Sets the sort order of the cursor query
collection.find({}).hint('a_1') // Set the cursor hint

All options are chainable, so one can do the following.

collection.find({}).maxTimeMS(1000).maxScan(100).skip(1).toArray(..)

Extends

Methods

addCursorFlag(flag, value){Cursor}

Add a cursor flag to the cursor

Name Type Description
flag string

The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial'].

value boolean

The flag boolean value.

Throws:

addQueryModifier(name, value){Cursor}

Add a query modifier to the cursor query

Name Type Description
name string

The query modifier (must start with $, such as $orderby etc)

value string | boolean | number

The modifier value.

Throws:

batchSize(value){Cursor}

Set the batch size for the cursor.

Name Type Description
value number

The number of documents to return per batch. See find command documentation.

Throws:

Clone the cursor

close(options, callback){Promise}

Close the cursor, sending a KillCursor command and emitting close.

Name Type Description
options object optional

Optional settings.

Name Type Description
skipKillCursors boolean optional

Bypass calling killCursors when closing the cursor.

callback Cursor~resultCallback optional

The result callback.

Returns:
Promise if no callback passed

collation(value){Cursor}

Set the collation options for the cursor.

Name Type Description
value object

The cursor collation options (MongoDB 3.4 or higher) settings for update operation (see 3.4 documentation for available fields).

Throws:

comment(value){Cursor}

Add a comment to the cursor query allowing for tracking the comment in the log.

Name Type Description
value string

The comment attached to this query.

Throws:

count(applySkipLimit, options, callback){Promise}

Get the count of documents for this cursor

Name Type Default Description
applySkipLimit boolean true optional

Should the count command apply limit and skip settings on the cursor or in the passed in options.

options object optional

Optional settings.

Name Type Description
skip number optional

The number of documents to skip.

limit number optional

The maximum amounts to count before aborting.

maxTimeMS number optional

Number of milliseconds to wait before aborting the query.

hint string optional

An index name hint for the query.

readPreference ReadPreference | string optional

The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).

callback Cursor~countResultCallback optional

The result callback.

Returns:
Promise if no callback passed

each(callback){null}

Iterates over all the documents for this cursor. As with {cursor.toArray},
not all of the elements will be iterated if this cursor had been previously accessed.
In that case, {cursor.rewind} can be used to reset the cursor. However, unlike
{cursor.toArray}, the cursor will only hold a maximum of batch size elements
at any given time if batch size is specified. Otherwise, the caller is responsible
for making sure that the entire result can fit the memory.

Name Type Description
callback Cursor~resultCallback

The result callback.

Deprecated
  • Yes
Throws:

explain(verbosity, callback){Promise}

Execute the explain for the cursor

For backwards compatibility, a verbosity of true is interpreted as "allPlansExecution"
and false as "queryPlanner". Prior to server version 3.6, aggregate()
ignores the verbosity parameter and executes in "queryPlanner".

Name Type Default Description
verbosity 'queryPlanner' | 'queryPlannerExtended' | 'executionStats' | 'allPlansExecution' | boolean true optional

An optional mode in which to run the explain.

callback Cursor~resultCallback optional

The result callback.

Returns:
Promise if no callback passed

filter(filter){Cursor}

Set the cursor query

Name Type Description
filter object

The filter object used for the cursor.

forEach(iterator, callback){Promise}

Iterates over all the documents for this cursor using the iterator, callback pattern.

Name Type Description
iterator Cursor~iteratorCallback

The iteration callback.

callback Cursor~endCallback

The end callback.

Throws:
Returns:
no callback supplied

hasNext(callback){Promise}

Check if there is any document still available in the cursor

Name Type Description
callback Cursor~resultCallback optional

The result callback.

Throws:
Returns:
Promise if no callback passed

Set the cursor hint

Name Type Description
hint object

If specified, then the query system will only consider plans using the hinted index.

isClosed(){boolean}

Is the cursor closed

limit(value){Cursor}

Set the limit for the cursor.

Name Type Description
value number

The limit for the cursor query.

Throws:

map(transform){Cursor}

Map all documents using the provided function

Name Type Description
transform function optional

The mapping transformation method.

Set the cursor max

Name Type Description
max object

Specify a $max value to specify the exclusive upper bound for a specific index in order to constrain the results of find(). The $max specifies the upper bound for all keys of a specific index in order.

maxAwaitTimeMS(value){Cursor}

Set a maxAwaitTimeMS on a tailing cursor query to allow to customize the timeout value for the option awaitData (Only supported on MongoDB 3.2 or higher, ignored otherwise)

Name Type Description
value number

Number of milliseconds to wait before aborting the tailed query.

Throws:

maxScan(maxScan){Cursor}

Set the cursor maxScan

Name Type Description
maxScan object

Constrains the query to only scan the specified number of documents when fulfilling the query

Deprecated
  • as of MongoDB 4.0

    maxTimeMS(value){Cursor}

    Set a maxTimeMS on the cursor query, allowing for hard timeout limits on queries (Only supported on MongoDB 2.6 or higher)

    Name Type Description
    value number

    Number of milliseconds to wait before aborting the query.

    Throws:

    Set the cursor min

    Name Type Description
    min object

    Specify a $min value to specify the inclusive lower bound for a specific index in order to constrain the results of find(). The $min specifies the lower bound for all keys of a specific index in order.

    next(callback){Promise}

    Get the next available document from the cursor, returns null if no more documents are available.

    Name Type Description
    callback Cursor~resultCallback optional

    The result callback.

    Throws:
    Returns:
    Promise if no callback passed

    This method will cause a stream in flowing-mode to stop emitting data events. Any data that becomes available will remain in the internal buffer.

    inherited pipe(destination, options){null}

    This method pulls all the data out of a readable stream, and writes it to the supplied destination, automatically managing the flow so that the destination is not overwhelmed by a fast readable stream.

    Name Type Description
    destination Writable

    The destination for writing data

    options object optional

    Pipe options

    project(value){Cursor}

    Sets a field projection for the query.

    Name Type Description
    value object

    The field projection object.

    Throws:

    inherited read(size){String|Buffer|null}

    The read() method pulls some data out of the internal buffer and returns it. If there is no data available, then it will return null.

    Name Type Description
    size number

    Optional argument to specify how much data to read.

    This method will cause the readable stream to resume emitting data events.

    returnKey(returnKey){Cursor}

    Set the cursor returnKey. If set to true, modifies the cursor to only return the index field or fields for the results of the query, rather than documents. If set to true and the query does not use an index to perform the read operation, the returned documents will not contain any fields.

    Name Type Description
    returnKey bool

    the returnKey value.

    inherited rewind(){null}

    Resets the cursor

    setCursorOption(field, value){Cursor}

    Set a node.js specific cursor option

    Name Type Description
    field string

    The cursor option to set ['numberOfRetries', 'tailableRetryInterval'].

    value object

    The field value.

    Throws:

    inherited setEncoding(encoding){null}

    Call this function to cause the stream to return strings of the specified encoding instead of Buffer objects.

    Name Type Description
    encoding string

    The encoding to use.

    setReadPreference(readPreference){Cursor}

    Set the ReadPreference for the cursor.

    Name Type Description
    readPreference string | ReadPreference

    The new read preference for the cursor.

    Throws:

    showRecordId(showRecordId){Cursor}

    Set the cursor showRecordId

    Name Type Description
    showRecordId object

    The $showDiskLoc option has now been deprecated and replaced with the showRecordId field. $showDiskLoc will still be accepted for OP_QUERY stye find.

    skip(value){Cursor}

    Set the skip for the cursor.

    Name Type Description
    value number

    The skip for the cursor query.

    Throws:

    snapshot(snapshot){Cursor}

    Set the cursor snapshot

    Name Type Description
    snapshot object

    The $snapshot operator prevents the cursor from returning a document more than once because an intervening write operation results in a move of the document.

    Deprecated
    • as of MongoDB 4.0

      sort(keyOrList, direction){Cursor}

      Sets the sort order of the cursor query.

      Name Type Description
      keyOrList string | array | object

      The key or keys set for the sort.

      direction number optional

      The direction of the sorting (1 or -1).

      Throws:

      stream(options){Cursor}

      Return a modified Readable stream including a possible transform method.

      Name Type Description
      options object optional

      Optional settings.

      Name Type Description
      transform function optional

      A transformation method applied to each document emitted by the stream.

      Returns:
      replace this method with transformStream in next major release

      toArray(callback){Promise}

      Returns an array of documents. The caller is responsible for making sure that there
      is enough memory to store the results. Note that the array only contains partial
      results when this cursor had been previously accessed. In that case,
      cursor.rewind() can be used to reset the cursor.

      Name Type Description
      callback Cursor~toArrayResultCallback optional

      The result callback.

      Throws:
      Returns:
      Promise if no callback passed

      transformStream(options){stream}

      Return a modified Readable stream that applies a given transform function, if supplied. If none supplied,
      returns a stream of unmodified docs.

      Name Type Description
      options object optional

      Optional settings.

      Name Type Description
      transform function optional

      A transformation method applied to each document emitted by the stream.

      inherited unpipe(destination){null}

      This method will remove the hooks set up for a previous pipe() call.

      Name Type Description
      destination Writable optional

      The destination for writing data

      inherited unshift(chunk){null}

      This is useful in certain cases where a stream is being consumed by a parser, which needs to "un-consume" some data that it has optimistically pulled out of the source, so that the stream can be passed on to some other party.

      Name Type Description
      chunk Buffer | string

      Chunk of data to unshift onto the read queue.

      inherited wrap(stream){null}

      Versions of Node prior to v0.10 had streams that did not implement the entire Streams API as it is today. (See "Compatibility" below for more information.)

      Name Type Description
      stream Stream

      An "old style" readable stream.

      Type Definitions

      countResultCallback(error, count)

      The callback format for results

      Name Type Description
      error MongoError

      An error instance representing the error during the execution.

      count number

      The count of documents.

      endCallback(error)

      The callback error format for the forEach iterator method

      Name Type Description
      error MongoError

      An error instance representing the error during the execution.

      iteratorCallback(doc)

      The callback format for the forEach iterator method

      Name Type Description
      doc Object

      An emitted document for the iterator

      resultCallback(error, result)

      The callback format for results

      Name Type Description
      error MongoError

      An error instance representing the error during the execution.

      result object | null | boolean

      The result object if the command was executed successfully.

      toArrayResultCallback(error, documents)

      The callback format for results

      Name Type Description
      error MongoError

      An error instance representing the error during the execution.

      documents Array.<object>

      All the documents the satisfy the cursor.

      Events

      Cursor stream close event

      Type:
      • null

      Cursor stream data event, fired for each document in the cursor.

      Type:
      • object

      Cursor stream end event

      Type:
      • null

      Cursor stream readable event

      Type:
      • null