Node.js MongoDB Driver API

Class: AggregationCursor

AggregationCursor

new AggregationCursor(){AggregationCursor}

lib/aggregation_cursor.js, line 45

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

Fires:
Returns:
AggregationCursor instance.

Extends

Methods

batchSize(value){AggregationCursor}

lib/aggregation_cursor.js, line 145

Set the batch size for the cursor.

Name Type Description
value number

The batchSize for the cursor.
Throws:
MongoError

clone(){AggregationCursor}

lib/aggregation_cursor.js, line 401

Clone the cursor

close(callback){Promise}

lib/aggregation_cursor.js, line 381

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

Name Type Description
callback AggregationCursor~resultCallback optional

The result callback.
Returns:
Promise if no callback passed

each(callback){null}

lib/aggregation_cursor.js, line 368

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 AggregationCursor~resultCallback

The result callback.
Throws:
MongoError
Example
// Correctly call the aggregation using a cursor and each

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Some docs for insertion
  var docs = [{
      title : "this is my title", author : "bob", posted : new Date() ,
      pageViews : 5, tags : [ "fun" , "good" , "fun" ], other : { foo : 5 },
      comments : [
        { author :"joe", text : "this is cool" }, { author :"sam", text : "this is bad" }
      ]}];

  // Create a collection
  var collection = db.collection('aggregation_each_example');
  // Insert the docs
  collection.insertMany(docs, {w: 1}, function(err, result) {

    // Execute aggregate, notice the pipeline is expressed as an Array
    var cursor = collection.aggregate([
        { $project : {
          author : 1,
          tags : 1
        }},
        { $unwind : "$tags" },
        { $group : {
          _id : {tags : "$tags"},
          authors : { $addToSet : "$author" }
        }}
      ], { cursor: { batchSize: 1 } });

    // Get all the aggregation results
    cursor.each(function(err, docs) {
      test.equal(null, err);

      if(docs == null) {
        db.close();
      }
    });
  });
});

explain(callback){Promise}

lib/aggregation_cursor.js, line 394

Execute the explain for the cursor

Name Type Description
callback AggregationCursor~resultCallback optional

The result callback.
Returns:
Promise if no callback passed

geoNear(document){AggregationCursor}

lib/aggregation_cursor.js, line 161

Add a geoNear stage to the aggregation pipeline

Name Type Description
document object

The geoNear stage document.

group(document){AggregationCursor}

lib/aggregation_cursor.js, line 174

Add a group stage to the aggregation pipeline

Name Type Description
document object

The group stage document.

hasNext(callback){Promise}

lib/aggregation_cursor.js, line 335

Check if there is any document still available in the cursor

Name Type Description
callback AggregationCursor~resultCallback optional

The result callback.
Throws:
MongoError
Returns:
Promise if no callback passed

isClosed(){boolean}

lib/aggregation_cursor.js, line 388

Is the cursor closed

limit(value){AggregationCursor}

lib/aggregation_cursor.js, line 187

Add a limit stage to the aggregation pipeline

Name Type Description
value number

The state limit value.

lookup(document){AggregationCursor}

lib/aggregation_cursor.js, line 254

Add a lookup stage to the aggregation pipeline

Name Type Description
document object

The lookup stage document.

match(document){AggregationCursor}

lib/aggregation_cursor.js, line 200

Add a match stage to the aggregation pipeline

Name Type Description
document object

The match stage document.

maxTimeMS(value){AggregationCursor}

lib/aggregation_cursor.js, line 213

Add a maxTimeMS stage to the aggregation pipeline

Name Type Description
value number

The state maxTimeMS value.

next(callback){Promise}

lib/aggregation_cursor.js, line 327

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

Name Type Description
callback AggregationCursor~resultCallback optional

The result callback.
Throws:
MongoError
Returns:
Promise if no callback passed
Examples
// Correctly call the aggregation using a cursor and next

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Some docs for insertion
  var docs = [{
      title : "this is my title", author : "bob", posted : new Date() ,
      pageViews : 5, tags : [ "fun" , "good" , "fun" ], other : { foo : 5 },
      comments : [
        { author :"joe", text : "this is cool" }, { author :"sam", text : "this is bad" }
      ]}];

  // Create a collection
  var collection = db.collection('aggregation_next_example');
  // Insert the docs
  collection.insertMany(docs, {w: 1}, function(err, result) {

    // Execute aggregate, notice the pipeline is expressed as an Array
    var cursor = collection.aggregate([
        { $project : {
          author : 1,
          tags : 1
        }},
        { $unwind : "$tags" },
        { $group : {
          _id : {tags : "$tags"},
          authors : { $addToSet : "$author" }
        }}
      ], { cursor: { batchSize: 1 } });

    // Get all the aggregation results
    cursor.next(function(err, docs) {
      test.equal(null, err);
      db.close();
    });
  });
});
// Call next on an aggregation cursor using a Promise

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Some docs for insertion
  var docs = [{
      title : "this is my title", author : "bob", posted : new Date() ,
      pageViews : 5, tags : [ "fun" , "good" , "fun" ], other : { foo : 5 },
      comments : [
        { author :"joe", text : "this is cool" }, { author :"sam", text : "this is bad" }
      ]}];

  // Create a collection
  var collection = db.collection('aggregation_next_example_with_promise');
  // Insert the docs
  collection.insertMany(docs, {w: 1}).then(function(result) {

    // Execute aggregate, notice the pipeline is expressed as an Array
    var cursor = collection.aggregate([
        { $project : {
          author : 1,
          tags : 1
        }},
        { $unwind : "$tags" },
        { $group : {
          _id : {tags : "$tags"},
          authors : { $addToSet : "$author" }
        }}
      ], { cursor: { batchSize: 1 } });
    // Get all the aggregation results
    cursor.next().then(function(docs) {
      db.close();
    }).catch(function(err) {
      console.dir(err)
    });
  });
});
// Call next on an aggregation 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');
  // Some docs for insertion
  var docs = [{
      title : "this is my title", author : "bob", posted : new Date() ,
      pageViews : 5, tags : [ "fun" , "good" , "fun" ], other : { foo : 5 },
      comments : [
        { author :"joe", text : "this is cool" }, { author :"sam", text : "this is bad" }
      ]}];

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

  // Insert the docs
  yield collection.insertMany(docs, {w: 1});

  // Execute aggregate, notice the pipeline is expressed as an Array
  var cursor = collection.aggregate([
      { $project : {
        author : 1,
        tags : 1
      }},
      { $unwind : "$tags" },
      { $group : {
        _id : {tags : "$tags"},
        authors : { $addToSet : "$author" }
      }}
    ], { cursor: { batchSize: 1 } });
  // Get all the aggregation results
  var doc = yield cursor.next();
  db.close();
});

out(destination){AggregationCursor}

lib/aggregation_cursor.js, line 228

Add a out stage to the aggregation pipeline

Name Type Description
destination number

The destination name.

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(document){AggregationCursor}

lib/aggregation_cursor.js, line 241

Add a project stage to the aggregation pipeline

Name Type Description
document object

The project stage document.

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.

redact(document){AggregationCursor}

lib/aggregation_cursor.js, line 267

Add a redact stage to the aggregation pipeline

Name Type Description
document object

The redact stage document.

inherited resume(){null}

lib/cursor.js, line 1162

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

rewind(){AggregationCursor}

lib/aggregation_cursor.js, line 407

Resets the cursor

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.

skip(value){AggregationCursor}

lib/aggregation_cursor.js, line 280

Add a skip stage to the aggregation pipeline

Name Type Description
value number

The state skip value.

sort(document){AggregationCursor}

lib/aggregation_cursor.js, line 293

Add a sort stage to the aggregation pipeline

Name Type Description
document object

The sort stage document.

toArray(callback){Promise}

lib/aggregation_cursor.js, line 350

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 AggregationCursor~toArrayResultCallback optional

The result callback.
Throws:
MongoError
Returns:
Promise if no callback passed
Example
// Correctly call the aggregation using a cursor and toArray

var MongoClient = require('mongodb').MongoClient,
  test = require('assert');
MongoClient.connect('mongodb://localhost:27017/test', function(err, db) {
  // Some docs for insertion
  var docs = [{
      title : "this is my title", author : "bob", posted : new Date() ,
      pageViews : 5, tags : [ "fun" , "good" , "fun" ], other : { foo : 5 },
      comments : [
        { author :"joe", text : "this is cool" }, { author :"sam", text : "this is bad" }
      ]}];

  // Create a collection
  var collection = db.collection('aggregation_toArray_example');
  // Insert the docs
  collection.insertMany(docs, {w: 1}, function(err, result) {

    // Execute aggregate, notice the pipeline is expressed as an Array
    var cursor = collection.aggregate([
        { $project : {
          author : 1,
          tags : 1
        }},
        { $unwind : "$tags" },
        { $group : {
          _id : {tags : "$tags"},
          authors : { $addToSet : "$author" }
        }}
      ], { cursor: { batchSize: 1 } });

    // Get all the aggregation results
    cursor.toArray(function(err, docs) {
      test.equal(null, err);
      test.equal(2, docs.length);
      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.

unwind(field){AggregationCursor}

lib/aggregation_cursor.js, line 306

Add a unwind stage to the aggregation pipeline

Name Type Description
field number

The unwind field name.

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

endCallback(error)

lib/aggregation_cursor.js, line 419

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/aggregation_cursor.js, line 413

The callback format for the forEach iterator method

Name Type Description
doc Object

An emitted document for the iterator

resultCallback(error, result)

lib/aggregation_cursor.js, line 361

The callback format for results

Name Type Description
error MongoError

An error instance representing the error during the execution.
result object | null

The result object if the command was executed successfully.

toArrayResultCallback(error, documents)

lib/aggregation_cursor.js, line 343

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/aggregation_cursor.js, line 114

AggregationCursor stream close event

Type:
  • null

data

lib/aggregation_cursor.js, line 100

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

Type:
  • object

end

lib/aggregation_cursor.js, line 107

AggregationCursor stream end event

Type:
  • null

readable

lib/aggregation_cursor.js, line 121

AggregationCursor stream readable event

Type:
  • null