Class: Cursor

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('oplogReplay', true)         // Set cursor as oplogReplay

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 maxScan

collection.find({}).maxScan(10)                                // Set the cursor maxScan

collection.find({}).maxTimeMS(1000)                            // Set the cursor maxTimeMS

collection.find({}).min(100)                                   // Set the cursor min

collection.find({}).returnKey(10)                              // Set the cursor returnKey

collection.find({}).setReadPreference(ReadPreference.PRIMARY)  // Set the cursor readPreference

collection.find({}).showRecordId(true)                         // Set the cursor showRecordId

collection.find({}).snapshot(true)                             // Set the cursor snapshot

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

• external:CoreCursor
• external:Readable

Methods

addCursorFlag(flag, value){Cursor}

lib/cursor.js, line 426

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:

MongoError

addQueryModifier(name, value){Cursor}

lib/cursor.js, line 454

Add a query modifier to the cursor query

Name	Type	Description
name	string	The query modifier (must start with $, such as $orderby etc)
value	boolean	The flag boolean value.

Throws:

MongoError

batchSize(value){Cursor}

lib/cursor.js, line 604

Set the batch size for the cursor.

Name	Type	Description
value	number	The batchSize for the cursor.

Throws:

MongoError

inherited clone(){Cursor}

lib/cursor.js, line 692

Clone the cursor

close(options, callback){Promise}

lib/cursor.js, line 1027

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}

lib/cursor.js, line 629

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:

MongoError

comment(value){Cursor}

lib/cursor.js, line 479

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:

MongoError

count(applySkipLimit, options, callback){Promise}

lib/cursor.js, line 950

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	null	optional Optional settings. Name Type Default Description skip number null optional The number of documents to skip. limit number null optional The maximum amounts to count before aborting. maxTimeMS number null optional Number of miliseconds to wait before aborting the query. hint string null optional An index name hint for the query. readPreference ReadPreference | string null 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}

lib/cursor.js, line 751

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 previouly 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:

MongoError

explain(callback){Promise}

lib/cursor.js, line 1110

Execute the explain for the cursor

Name	Type	Description
callback	Cursor~resultCallback	optional The result callback.

Returns:

Promise if no callback passed

filter(filter){Cursor}

lib/cursor.js, line 281

Set the cursor query

Name	Type	Description
filter	object	The filter object used for the cursor.

forEach(iterator, callback){null}

lib/cursor.js, line 812

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:

MongoError

hasNext(callback){Promise}

lib/cursor.js, line 230

Check if there is any document still available in the cursor

Name	Type	Description
callback	Cursor~resultCallback	optional The result callback.

Throws:

MongoError

Returns:

Promise if no callback passed

hint(hint){Cursor}

lib/cursor.js, line 311

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}

lib/cursor.js, line 1082

Is the cursor closed

limit(value){Cursor}

lib/cursor.js, line 641

Set the limit for the cursor.

Name	Type	Description
value	number	The limit for the cursor query.

Throws:

MongoError

map(transform){Cursor}

lib/cursor.js, line 1065

Map all documents using the provided function

Name	Type	Description
transform	function	optional The mapping transformation method.

max(max){Cursor}

lib/cursor.js, line 339

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}

lib/cursor.js, line 495

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:

MongoError

maxScan(maxScan){Cursor}

lib/cursor.js, line 296

Set the cursor maxScan

Name	Type	Description
maxScan	object	Constrains the query to only scan the specified number of documents when fulfilling the query

maxTimeMS(value){Cursor}

lib/cursor.js, line 515

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:

MongoError

min(min){Cursor}

lib/cursor.js, line 326

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}

lib/cursor.js, line 257

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:

MongoError

Returns:

Promise if no callback passed

inherited pause(){null}

lib/cursor.js, line 1222

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}

lib/cursor.js, line 1228

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}

lib/cursor.js, line 537

Sets a field projection for the query.

Name	Type	Description
value	object	The field projection object.

Throws:

MongoError

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

lib/cursor.js, line 1202

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.

inherited resume(){null}

lib/cursor.js, line 1216

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

returnKey(returnKey){Cursor}

lib/cursor.js, line 354

Set the cursor returnKey

Name	Type	Description
returnKey	object	Only return the index field or fields for the results of the query. If $returnKey is set to true and the query does not use an index to perform the read operation, the returned documents will not contain any fields. Use one of the following forms:

inherited rewind(){null}

lib/cursor.js, line 698

Resets the cursor

setCursorOption(field, value){Cursor}

lib/cursor.js, line 401

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:

MongoError

inherited setEncoding(encoding){null}

lib/cursor.js, line 1209

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}

lib/cursor.js, line 838

Set the ReadPreference for the cursor.

Name	Type	Description
readPreference	string | ReadPreference	The new read preference for the cursor.

Throws:

MongoError

showRecordId(showRecordId){Cursor}

lib/cursor.js, line 369

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}

lib/cursor.js, line 667

Set the skip for the cursor.

Name	Type	Description
value	number	The skip for the cursor query.

Throws:

MongoError

snapshot(snapshot){Cursor}

lib/cursor.js, line 384

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.

sort(keyOrList, direction){Cursor}

lib/cursor.js, line 554

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:

MongoError

stream(options){Cursor}

lib/cursor.js, line 1099

Return a modified Readable stream including a possible transform method.

Name	Type	Default	Description
options	object	null	optional Optional settings. Name Type Default Description transform function null optional A transformation method applied to each document emitted by the stream.

toArray(callback){Promise}

lib/cursor.js, line 874

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 contain partial
results when this cursor had been previouly accessed. In that case,
cursor.rewind() can be used to reset the cursor.

Name	Type	Description
callback	Cursor~toArrayResultCallback	optional The result callback.

Throws:

MongoError

Returns:

Promise if no callback passed

inherited unpipe(destination){null}

lib/cursor.js, line 1236

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}

lib/cursor.js, line 1243

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}

lib/cursor.js, line 1250

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)

lib/cursor.js, line 930

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)

lib/cursor.js, line 798

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)

lib/cursor.js, line 792

The callback format for the forEach iterator method

Name	Type	Description
doc	Object	An emitted document for the iterator

resultCallback(error, result)

lib/cursor.js, line 685

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)

lib/cursor.js, line 857

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

close

lib/cursor.js, line 180

Cursor stream close event

Type:

• null

data

lib/cursor.js, line 166

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

Type:

• object

end

lib/cursor.js, line 173

Cursor stream end event

Type:

• null

readable

lib/cursor.js, line 187

Cursor stream readable event

Type:

• null