Class: 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('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

Methods

addCursorFlag(flag, value){Cursor} lib/cursor.js, line 430

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 448

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 578

Set the batch size for the cursor.

Name	Type	Description
`value`	number	The batchSize for the cursor.

Throws:

MongoError

Example

// A simple example showing the use of batchSize on the cursor, batchSize only regulates how many
documents are returned for each batch using the getMoreCommand against the MongoDB server

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_batch_size_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do normal ascending sort
    collection.find().batchSize(1).nextObject(function(err, item) {
      test.equal(null, err);
      test.equal(1, item.a);

      db.close();
    });
  });
});

inherited clone(){Cursor} lib/cursor.js, line 647

Clone the cursor

close(callback){Promise} lib/cursor.js, line 984

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

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

Returns:

Promise if no callback passed

Examples

// A simple example showing the use of the cursor close function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a lot of documents to insert
  var docs = []
  for(var i = 0; i < 100; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_close_function_on_cursor');

  // Insert documents into collection
  collection.insertMany(docs, {w:1}, function(err, ids) {
    // Perform a find to get a cursor
    var cursor = collection.find();

    // Fetch the first object
    cursor.nextObject(function(err, object) {
      test.equal(null, err);

      // Close the cursor, this is the same as reseting the query
      cursor.close(function(err, result) {
        test.equal(null, err);

        db.close();
      });
    });
  });
});

// A simple example showing the use of the cursor close function using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a lot of documents to insert
  var docs = []
  for(var i = 0; i < 100; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_close_function_on_cursor_with_promise');

  // Insert documents into collection
  collection.insertMany(docs, {w:1}).then(function(ids) {
    // Perform a find to get a cursor
    var cursor = collection.find();

    // Fetch the first object
    cursor.nextObject().then(function(object) {

      // Close the cursor, this is the same as reseting the query
      cursor.close().then(function(result) {
        db.close();
      });
    });
  });
});

// A simple example showing the use of the cursor close function using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a lot of documents to insert
  var docs = []
  for(var i = 0; i < 100; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_close_function_on_cursor_with_generators');

  // Insert documents into collection
  yield collection.insertMany(docs, {w:1});
  // Perform a find to get a cursor
  var cursor = collection.find();

  // Fetch the first object
  yield cursor.nextObject();

  // Close the cursor, this is the same as reseting the query
  yield cursor.close();
  db.close();
});

collation(value){Cursor} lib/cursor.js, line 596

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 469

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 909

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 milliseconds 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

Examples

// A simple example showing the count function of the cursor.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Creat collection
  var collection = db.collection('cursor_count_collection');

  // Insert some docs
  collection.insertMany([{a:1}, {a:2}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do a find and get the cursor count
    collection.find().count(function(err, count) {
      test.equal(null, err);
      test.equal(2, count);

      db.close();
    })
  });
});

// A simple example showing the count function of the cursor using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Creat collection
  var collection = db.collection('cursor_count_collection_with_promise');

  // Insert some docs
  collection.insertMany([{a:1}, {a:2}], {w:1}).then(function(docs) {

    // Do a find and get the cursor count
    collection.find().count().then(function(count) {
      test.equal(2, count);

      db.close();
    })
  });
});

// A simple example showing the count function of the cursor using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Creat collection
  var collection = db.collection('cursor_count_collection_with_generators');

  // Insert some docs
  yield collection.insertMany([{a:1}, {a:2}], {w:1});

  // Do a find and get the cursor count
  var count = yield collection.find().count();
  test.equal(2, count);

  db.close();
});

each(callback){null} lib/cursor.js, line 717

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

Throws:

MongoError

Example

// A simple example iterating over a query using the each function of the cursor.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('test_to_a_after_each');

  // Insert a document in the collection
  collection.insertOne({'a':1}, {w:1}, function(err, ids) {

    // Grab a cursor
    var cursor = collection.find();
    // Execute the each command, triggers for each document
    cursor.each(function(err, item) {

      // If the item is null then the cursor is exhausted/empty and closed
      if(item == null) {
        // Show that the cursor is closed
        cursor.toArray(function(err, items) {
          test.equal(null, err);

          // Let's close the db
          db.close();
        });
      };
    });
  });
});

explain(callback){Promise} lib/cursor.js, line 1057

Execute the explain for the cursor

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

Returns:

Promise if no callback passed

Examples

// A simple example showing the use of the cursor explain function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_explain_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do normal ascending sort
    collection.find().explain(function(err, explaination) {
      test.equal(null, err);

      db.close();
    });
  });
});

// A simple example showing the use of the cursor explain function using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_explain_collection_with_promise');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}).then(function(docs) {

    // Do normal ascending sort
    collection.find().explain().then(function(explaination) {
      db.close();
    });
  });
});

// A simple example showing the use of the cursor explain function using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection
  var collection = db.collection('simple_explain_collection_with_generators');

  // Insert some documents we can sort on
  yield collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1});

  // Do normal ascending sort
  yield collection.find().explain();
  db.close();
});

filter(filter){Cursor} lib/cursor.js, line 297

Set the cursor query

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

forEach(iterator, callback){null} lib/cursor.js, line 778

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

Example

// A simple example iterating over a query using the forEach function of the cursor.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('test_to_a_after_for_each');

  // Insert a document in the collection
  collection.insertOne({'a':1}, {w:1}, function(err, ids) {
    // Count of documents returned
    var count = 0;
    // Grab a cursor
    var cursor = collection.find();
    // Execute the each command, triggers for each document
    cursor.forEach(function(doc) {
      test.ok(doc != null);
      count = count + 1;
    }, function(err) {
      test.equal(null, err);
      test.equal(1, count);
      db.close();
    });
  });
});

hasNext(callback){Promise} lib/cursor.js, line 215

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 325

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 1023

Is the cursor closed

Example

// A simple example showing the use of the cursor close function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a lot of documents to insert
  var docs = []
  for(var i = 0; i < 100; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_is_close_function_on_cursor');

  // Insert documents into collection
  collection.insertMany(docs, {w:1}, function(err, ids) {
    // Perform a find to get a cursor
    var cursor = collection.find();

    // Fetch the first object
    cursor.nextObject(function(err, object) {
      test.equal(null, err);

      // Close the cursor, this is the same as reseting the query
      cursor.close(function(err, result) {
        test.equal(null, err);
        test.equal(true, cursor.isClosed());

        db.close();
      });
    });
  });
});

limit(value){Cursor} lib/cursor.js, line 610

Set the limit for the cursor.

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

Throws:

MongoError

Example

// A simple example showing the use of limit on the cursor

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_limit_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Limit to only one document returned
    collection.find().limit(1).toArray(function(err, items) {
      test.equal(null, err);
      test.equal(1, items.length);

      db.close();
    });
  });
});

map(transform){Cursor} lib/cursor.js, line 1006

Map all documents using the provided function

Name	Type	Description
`transform`	function	optional The mapping transformation method.

max(max){Cursor} lib/cursor.js, line 353

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 484

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 311

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 500

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 339

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

Examples

// A simple example showing the use of next.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_next_object_collection_with_next');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do normal ascending sort
    var cursor = collection.find();
    // Perform hasNext check
    cursor.hasNext(function(err, r) {
      test.equal(null, err);
      test.ok(r);

      cursor.next(function(err, r) {
        test.equal(null, err);
        test.equal(1, r.a);

        cursor.hasNext(function(err, r) {
          test.equal(null, err);
          test.ok(r);

          cursor.next(function(err, r) {
            test.equal(null, err);
            test.equal(2, r.a);

            cursor.hasNext(function(err, r) {
              test.equal(null, err);
              test.ok(r);

              cursor.next(function(err, r) {
                test.equal(null, err);
                test.equal(3, r.a);

                cursor.hasNext(function(err, r) {
                  test.equal(null, err);
                  test.ok(!r);

                  db.close();
                });
              });
            });
          });
        });
      });
    });
  });
});

// A simple example showing the use of next and co module to iterate over cursor

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection
  var collection = db.collection('simple_next_object_collection_next_with_generators');

  // Insert some documents we can sort on
  yield collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1});

  // Get a cursor
  var cursor = collection.find({});

  // Get the document
  var doc = null;
  var docs = [];

  // Iterate over the cursor
  while(yield cursor.hasNext()) {
    docs.push(yield cursor.next());
  }

  // Validate the correct number of elements
  test.equal(3, docs.length);
  db.close();
});

nextObject(callback){Promise} lib/cursor.js, line 667

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.

Deprecated

Throws:

MongoError

Returns:

Promise if no callback passed

Examples

// A simple example showing the use of nextObject.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_next_object_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do normal ascending sort
    collection.find().nextObject(function(err, item) {
      test.equal(null, err);
      test.equal(1, item.a);

      db.close();
    });
  });
});

// A simple example showing the use of nextObject using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_next_object_collection_with_promise');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}).then(function(docs) {

    // Do normal ascending sort
    collection.find().nextObject().then(function(item) {
      test.equal(1, item.a);

      db.close();
    });
  });
});

// A simple example showing the use of nextObject using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection
  var collection = db.collection('simple_next_object_collection_with_generators');

  // Insert some documents we can sort on
  yield collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1});

  // Do normal ascending sort
  var item = yield collection.find().nextObject();
  test.equal(1, item.a);

  db.close();
});

inherited pause(){null} lib/cursor.js, line 1168

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 1174

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 520

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 1148

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 1162

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

returnKey(returnKey){Cursor} lib/cursor.js, line 367

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 653

Resets the cursor

setCursorOption(field, value){Cursor} lib/cursor.js, line 411

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 1155

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 800

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 381

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 629

Set the skip for the cursor.

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

Throws:

MongoError

Example

// A simple example showing the use of skip on the cursor

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_skip_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Skip one document
    collection.find().skip(1).nextObject(function(err, item) {
      test.equal(null, err);
      test.equal(2, item.a);

      db.close();
    });
  });
});

snapshot(snapshot){Cursor} lib/cursor.js, line 395

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 536

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

Example

// A simple example showing the use of sort on the cursor.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection
  var collection = db.collection('simple_sort_collection');

  // Insert some documents we can sort on
  collection.insertMany([{a:1}, {a:2}, {a:3}], {w:1}, function(err, docs) {
    test.equal(null, err);

    // Do normal ascending sort
    collection.find().sort({'a': 1}).nextObject(function(err, item) {
      test.equal(null, err);
      test.equal(1, item.a);

      // Do normal descending sort, with new syntax that enforces ordering of sort keys
      collection.find().sort([['a', -1]]).nextObject(function(err, item) {
        test.equal(null, err);
        test.equal(3, item.a);

        db.close();
      });
    });
  });
});

stream(options){Cursor} lib/cursor.js, line 1044

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.

Examples

// A simple example showing the use of the cursor stream function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a lot of documents to insert
  var docs = []
  for(var i = 0; i < 100; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_stream_function');

  // Insert documents into collection
  collection.insertMany(docs, {w:1}, function(err, ids) {
    // Perform a find to get a cursor
    var stream = collection.find().stream();

    // Execute find on all the documents
    stream.on('end', function() {
      db.close();
    });

    stream.on('data', function(data) {
      test.ok(data != null);
    });
  });
});

// A simple example showing the use of the cursorstream pause function.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a lot of documents to insert
  var docs = []
  var fetchedDocs = [];
  for(var i = 0; i < 2; i++) {
    docs.push({'a':i})
  }

  // Create a collection
  var collection = db.collection('test_cursorstream_pause');

  // Insert documents into collection
  collection.insertMany(docs, {w:1}, function(err, ids) {
    // Perform a find to get a cursor
    var stream = collection.find().stream();

    // For each data item
    stream.on("data", function(item) {
      fetchedDocs.push(item)
      // Pause stream
      stream.pause();

      // Restart the stream after 1 miliscecond
      setTimeout(function() {
        fetchedDocs.push(null);
        stream.resume();
      }, 1);
    });

    // When the stream is done
    stream.on("end", function() {
      test.equal(null, fetchedDocs[1]);
      db.close();
    });
  });
});

toArray(callback){Promise} lib/cursor.js, line 832

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

MongoError

Returns:

Promise if no callback passed

Examples

// An example showing the information returned by indexInformation

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection to hold our documents
  var collection = db.collection('test_array');

  // Insert a test document
  collection.insertOne({'b':[1, 2, 3]}, {w:1}, function(err, ids) {

    // Retrieve all the documents in the collection
    collection.find().toArray(function(err, documents) {
      test.equal(1, documents.length);
      test.deepEqual([1, 2, 3], documents[0].b);

      db.close();
    });
  });
});

// An example showing the information returned by indexInformation using a Promise.

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {

  // Create a collection to hold our documents
  var collection = db.collection('test_array_with_promise');

  // Insert a test document
  collection.insertOne({'b':[1, 2, 3]}, {w:1}).then(function(ids) {

    // Retrieve all the documents in the collection
    collection.find().toArray().then(function(documents) {
      test.equal(1, documents.length);
      test.deepEqual([1, 2, 3], documents[0].b);

      db.close();
    });
  });
});

// An example showing the information returned by indexInformation using a Generator and the co module.

var MongoClient = require('mongodb').MongoClient,
  co = require('co');
  test = require('assert');

co(function*() {
  var db = yield MongoClient.connect('mongodb://localhost:27017/test');

  // Create a collection to hold our documents
  var collection = db.collection('test_array_with_generators');

  // Insert a test document
  yield collection.insertOne({'b':[1, 2, 3]}, {w:1});

  // Retrieve all the documents in the collection
  var documents = yield collection.find().toArray();
  test.equal(1, documents.length);
  test.deepEqual([1, 2, 3], documents[0].b);

  db.close();
});

inherited unpipe(destination){null} lib/cursor.js, line 1182

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 1189

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 1196

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 889

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 764

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 758

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 640

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 815

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 182

Cursor stream close event

Type:

null

data lib/cursor.js, line 168

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

Type:

object

end lib/cursor.js, line 175

Cursor stream end event

Type:

null

readable lib/cursor.js, line 189

Cursor stream readable event

Type:

null

Node.js MongoDB Driver API

Class: Cursor

new Cursor(){Cursor}

Properties:

Fires:

Returns:

Example

Extends

Methods

addCursorFlag(flag, value){Cursor}

Throws:

addQueryModifier(name, value){Cursor}

Throws:

batchSize(value){Cursor}

Throws:

Example

inherited clone(){Cursor}

close(callback){Promise}

Returns:

Examples

collation(value){Cursor}

Throws:

comment(value){Cursor}

Throws:

count(applySkipLimit, options, callback){Promise}

Returns:

Examples

each(callback){null}

Throws:

Example

explain(callback){Promise}

Returns:

Examples

filter(filter){Cursor}

forEach(iterator, callback){null}

Throws:

Example

hasNext(callback){Promise}

Throws:

Returns:

hint(hint){Cursor}

isClosed(){boolean}

Example

limit(value){Cursor}

Throws:

Example

map(transform){Cursor}

max(max){Cursor}

maxAwaitTimeMS(value){Cursor}

Throws:

maxScan(maxScan){Cursor}

maxTimeMS(value){Cursor}

Throws:

min(min){Cursor}

next(callback){Promise}

Throws:

Returns:

Examples

nextObject(callback){Promise}

Throws:

Returns:

Examples

inherited pause(){null}

inherited pipe(destination, options){null}

project(value){Cursor}

Throws:

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

inherited resume(){null}

returnKey(returnKey){Cursor}

inherited rewind(){null}

setCursorOption(field, value){Cursor}

Throws:

inherited setEncoding(encoding){null}

setReadPreference(readPreference){Cursor}

Throws:

showRecordId(showRecordId){Cursor}

skip(value){Cursor}

Throws:

Example

snapshot(snapshot){Cursor}