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('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}

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 boolean

The flag boolean value.

Throws:

batchSize(value){Cursor}

Set the batch size for the cursor.

Name Type Description
value number

The batchSize for the cursor.

Throws:
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(); }); }); });

Clone the cursor

close(callback){Promise}

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}

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

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

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}

Set the cursor query

Name Type Description
filter object

The filter object used for the cursor.

forEach(iterator, callback){null}

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

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

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}

Set the limit for the cursor.

Name Type Description
value number

The limit for the cursor query.

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

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

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

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
  • Yes
Throws:
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();
});

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

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}

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

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}

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

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}

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

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