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 flagstring The flag to set, must be one of following ['tailable', 'oplogReplay', 'noCursorTimeout', 'awaitData', 'partial'].
valueboolean The flag boolean value.
Throws:
-
addQueryModifier(name, value){Cursor}
-
Add a query modifier to the cursor query
Name Type Description namestring The query modifier (must start with $, such as $orderby etc)
valuestring | boolean | number The modifier value.
Throws:
-
batchSize(value){Cursor}
-
Set the batch size for the cursor.
Name Type Description valuenumber 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 optionsobject optional Optional settings.
Name Type Description skipKillCursorsboolean optional Bypass calling killCursors when closing the cursor.
callbackCursor~resultCallback optional The result callback.
Returns:
Promise if no callback passed
-
collation(value){Cursor}
-
Set the collation options for the cursor.
Name Type Description valueobject 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 valuestring The comment attached to this query.
Throws:
-
count(applySkipLimit, options, callback){Promise}
-
Get the count of documents for this cursor
Name Type Default Description applySkipLimitboolean true optional Should the count command apply limit and skip settings on the cursor or in the passed in options.
optionsobject optional Optional settings.
Name Type Description skipnumber optional The number of documents to skip.
limitnumber optional The maximum amounts to count before aborting.
maxTimeMSnumber optional Number of milliseconds to wait before aborting the query.
hintstring optional An index name hint for the query.
readPreferenceReadPreference | string optional The preferred read preference (ReadPreference.PRIMARY, ReadPreference.PRIMARY_PREFERRED, ReadPreference.SECONDARY, ReadPreference.SECONDARY_PREFERRED, ReadPreference.NEAREST).
callbackCursor~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 callbackCursor~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.
callbackCursor~resultCallback optional The result callback.
Returns:
Promise if no callback passed
-
filter(filter){Cursor}
-
Set the cursor query
Name Type Description filterobject 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 iteratorCursor~iteratorCallback The iteration callback.
callbackCursor~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 callbackCursor~resultCallback optional The result callback.
Throws:
Returns:
Promise if no callback passed
-
hint(hint){Cursor}
-
Set the cursor hint
Name Type Description hintobject 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 valuenumber The limit for the cursor query.
Throws:
-
map(transform){Cursor}
-
Map all documents using the provided function
Name Type Description transformfunction optional The mapping transformation method.
-
max(max){Cursor}
-
Set the cursor max
Name Type Description maxobject 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 valuenumber Number of milliseconds to wait before aborting the tailed query.
Throws:
-
maxScan(maxScan){Cursor}
-
Set the cursor maxScan
Name Type Description maxScanobject 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 valuenumber Number of milliseconds to wait before aborting the query.
Throws:
-
min(min){Cursor}
-
Set the cursor min
Name Type Description minobject 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 callbackCursor~resultCallback optional The result callback.
Throws:
Returns:
Promise if no callback passed
-
inherited pause(){null}
-
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 destinationWritable The destination for writing data
optionsobject optional Pipe options
-
project(value){Cursor}
-
Sets a field projection for the query.
Name Type Description valueobject 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 sizenumber Optional argument to specify how much data to read.
-
inherited resume(){null}
-
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 returnKeybool the returnKey value.
-
inherited rewind(){null}
-
Resets the cursor
-
setCursorOption(field, value){Cursor}
-
Set a node.js specific cursor option
Name Type Description fieldstring The cursor option to set ['numberOfRetries', 'tailableRetryInterval'].
valueobject 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 encodingstring The encoding to use.
-
setReadPreference(readPreference){Cursor}
-
Set the ReadPreference for the cursor.
Name Type Description readPreferencestring | ReadPreference The new read preference for the cursor.
Throws:
-
showRecordId(showRecordId){Cursor}
-
Set the cursor showRecordId
Name Type Description showRecordIdobject 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 valuenumber The skip for the cursor query.
Throws:
-
snapshot(snapshot){Cursor}
-
Set the cursor snapshot
Name Type Description snapshotobject 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 keyOrListstring | array | object The key or keys set for the sort.
directionnumber 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 optionsobject optional Optional settings.
Name Type Description transformfunction 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 callbackCursor~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 optionsobject optional Optional settings.
Name Type Description transformfunction 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 destinationWritable 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 chunkBuffer | 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 streamStream An "old style" readable stream.
Type Definitions
-
countResultCallback(error, count)
-
The callback format for results
Name Type Description errorMongoError An error instance representing the error during the execution.
countnumber The count of documents.
-
endCallback(error)
-
The callback error format for the forEach iterator method
Name Type Description errorMongoError An error instance representing the error during the execution.
-
iteratorCallback(doc)
-
The callback format for the forEach iterator method
Name Type Description docObject An emitted document for the iterator
-
resultCallback(error, result)
-
The callback format for results
Name Type Description errorMongoError An error instance representing the error during the execution.
resultobject | null | boolean The result object if the command was executed successfully.
-
toArrayResultCallback(error, documents)
-
The callback format for results
Name Type Description errorMongoError An error instance representing the error during the execution.
documentsArray.<object> All the documents the satisfy the cursor.
Events
-
close
-
Cursor stream close event
Type:
- null
-
data
-
Cursor stream data event, fired for each document in the cursor.
Type:
- object
-
end
-
Cursor stream end event
Type:
- null
-
readable
-
Cursor stream readable event
Type:
- null