Aggregate

Mongoose

Schema

Connection

Document

Model

Query

QueryCursor

Aggregate

AggregationCursor

Schematype

Virtualtype

Error

SchemaArray

DocumentArrayPath

SubdocumentPath

Aggregate()

Parameters

  • [pipeline] «Array» aggregation pipeline as an array of objects

  • [model] «Model» the model to use with this aggregate.

Aggregate constructor used for building aggregation pipelines. Do not instantiate this class directly, use Model.aggregate() instead.

Example:

  1. const aggregate = Model.aggregate([
  2.   { $project: { a: 1, b: 1 } },
  3.   { $skip: 5 }
  4. ]);
  6. Model.
  7.   aggregate([{ $match: { age: { $gte: 21 }}}]).
  8.   unwind('tags').
  9.   exec(callback);

Note:

  • The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
  • Mongoose does not cast pipeline stages. The below will not work unless _id is a string in the database
  1.   new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]);
  2.   // Do this instead to cast to an ObjectId
  3.   new Aggregate([{ $match: { _id: mongoose.Types.ObjectId('00000000000000000000000a') } }]);

Aggregate.prototype.Symbol.asyncIterator()

Returns an asyncIterator for use with [for/await/of loops](https://thecodebarbarian.com/getting-started-with-async-iterators-in-node-js You do not need to call this function explicitly, the JavaScript runtime will call it for you.

Example

  1. const agg = Model.aggregate([{ $match: { age: { $gte: 25 } } }]);
  2. for await (const doc of agg) {
  3.   console.log(doc.name);
  4. }

Node.js 10.x supports async iterators natively without any flags. You can enable async iterators in Node.js 8.x using the --harmony_async_iteration flag.

Note: This function is not set if Symbol.asyncIterator is undefined. If Symbol.asyncIterator is undefined, that means your Node.js version does not support async iterators.

Aggregate.prototype.addFields()

Parameters
  • arg «Object» field specification
Returns:
  • «Aggregate»

Appends a new $addFields operator to this aggregate pipeline. Requires MongoDB v3.4+ to work

Examples:

  1. // adding new fields based on existing fields
  2. aggregate.addFields({
  3.     newField: '$b.nested'
  4.   , plusTen: { $add: ['$val', 10]}
  5.   , sub: {
  6.        name: '$a'
  7.     }
  8. })
  10. // etc
  11. aggregate.addFields({ salary_k: { $divide: [ "$salary", 1000 ] } });

Aggregate.prototype.allowDiskUse()

Parameters

  • value «Boolean» Should tell server it can use hard drive to store data during aggregation.

  • [tags] «Array» optional tags for this query

Sets the allowDiskUse option for the aggregation query (ignored for < 2.6.0)

Example:

  1. await Model.aggregate([{ $match: { foo: 'bar' } }]).allowDiskUse(true);

Aggregate.prototype.append()

Parameters
  • ops «Object» operator(s) to append
Returns:
  • «Aggregate»

Appends new operators to this aggregate pipeline

Examples:

  1. aggregate.append({ $project: { field: 1 }}, { $limit: 2 });
  3. // or pass an array
  4. const pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
  5. aggregate.append(pipeline);

Aggregate.prototype.catch()

Parameters
  • [reject] «Function»
Returns:
  • «Promise»

Executes the query returning a Promise which will be resolved with either the doc(s) or rejected with the error. Like .then(), but only takes a rejection handler.

Aggregate.prototype.collation()

Parameters
  • collation «Object» options
Returns:
  • «Aggregate» this

Adds a collation

Example:

  1. Model.aggregate(..).collation({ locale: 'en_US', strength: 1 }).exec();

Aggregate.prototype.count()

Parameters
  • the «String» name of the count field
Returns:
  • «Aggregate»

Appends a new $count operator to this aggregate pipeline.

Examples:

  1. aggregate.count("userCount");

Aggregate.prototype.cursor()

Parameters
  • options «Object»

  • options.batchSize «Number» set the cursor batch size

  • [options.useMongooseAggCursor] «Boolean» use experimental mongoose-specific aggregation cursor (for eachAsync() and other query cursor semantics)

Returns:
  • «Aggregate» this

Sets the cursor option option for the aggregation query (ignored for < 2.6.0). Note the different syntax below: .exec() returns a cursor object, and no callback is necessary.

Example:

  1. const cursor = Model.aggregate(..).cursor({ batchSize: 1000 }).exec();
  2. cursor.eachAsync(function(doc, i) {
  3.   // use doc
  4. });

Aggregate.prototype.exec()

Parameters
  • [callback] «Function»
Returns:
  • «Promise»

Executes the aggregate pipeline on the currently bound Model.

Example:

  1. aggregate.exec(callback);
  3. // Because a promise is returned, the `callback` is optional.
  4. const promise = aggregate.exec();
  5. promise.then(..);

Aggregate.prototype.explain()

Parameters
  • callback «Function»
Returns:
  • «Promise»

Execute the aggregation with explain

Example:

  1. Model.aggregate(..).explain(callback)

Aggregate.prototype.facet()

Parameters
  • facet «Object» options
Returns:
  • «Aggregate» this

Combines multiple aggregation pipelines.

Example:

  1. Model.aggregate(...)
  2.  .facet({
  3.    books: [{ groupBy: '$author' }],
  4.    price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }]
  5.  })
  6.  .exec();
  8. // Output: { books: [...], price: [{...}, {...}] }

Aggregate.prototype.graphLookup()

Parameters
  • options «Object» to $graphLookup as described in the above link
Returns:
  • «Aggregate»

Appends new custom $graphLookup operator(s) to this aggregate pipeline, performing a recursive search on a collection.

Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if { allowDiskUse: true } is specified.

Examples:

  1. // Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
  2.  aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites

Aggregate.prototype.group()

Parameters
  • arg «Object» $group operator contents
Returns:
  • «Aggregate»

Appends a new custom $group operator to this aggregate pipeline.

Examples:

  1. aggregate.group({ _id: "$department" });

Aggregate.prototype.hint()

Parameters
  • value «Object|String» a hint object or the index name

Sets the hint option for the aggregation query (ignored for < 3.6.0)

Example:

  1. Model.aggregate(..).hint({ qty: 1, category: 1 }).exec(callback)

Aggregate.prototype.limit()

Parameters
  • num «Number» maximum number of records to pass to the next stage
Returns:
  • «Aggregate»

Appends a new $limit operator to this aggregate pipeline.

Examples:

  1. aggregate.limit(10);

Aggregate.prototype.lookup()

Parameters
  • options «Object» to $lookup as described in the above link
Returns:
  • «Aggregate*» @api public

Appends new custom $lookup operator to this aggregate pipeline.

Examples:

  1. aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });

Aggregate.prototype.match()

Parameters
  • arg «Object» $match operator contents
Returns:
  • «Aggregate»

Appends a new custom $match operator to this aggregate pipeline.

Examples:

  1. aggregate.match({ department: { $in: [ "sales", "engineering" ] } });

Aggregate.prototype.model()

Parameters
  • [model] «Model» set the model associated with this aggregate.
Returns:
  • «Model»

Get/set the model that this aggregation will execute on.

Example:

  1. const aggregate = MyModel.aggregate([{ $match: { answer: 42 } }]);
  2. aggregate.model() === MyModel; // true
  4. // Change the model. There's rarely any reason to do this.
  5. aggregate.model(SomeOtherModel);
  6. aggregate.model() === SomeOtherModel; // true

Aggregate.prototype.near()

Parameters
  • arg «Object»
Returns:
  • «Aggregate»

Appends a new $geoNear operator to this aggregate pipeline.

NOTE:

MUST be used as the first operator in the pipeline.

Examples:

  1. aggregate.near({
  2.   near: [40.724, -73.997],
  3.   distanceField: "dist.calculated", // required
  4.   maxDistance: 0.008,
  5.   query: { type: "public" },
  6.   includeLocs: "dist.location",
  7.   uniqueDocs: true,
  8.   num: 5
  9. });

Aggregate.prototype.option()

Parameters
Returns:
  • «Aggregate» this

Lets you set arbitrary options, for middleware or plugins.

Example:

  1. const agg = Model.aggregate(..).option({ allowDiskUse: true }); // Set the `allowDiskUse` option
  2. agg.options; // `{ allowDiskUse: true }`

Aggregate.prototype.options

Type:
  • «property»

Contains options passed down to the aggregate command.

Supported options are

Aggregate.prototype.pipeline()

Returns:
  • «Array»

Returns the current pipeline

Example:

  1. MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]

Aggregate.prototype.project()

Parameters
  • arg «Object|String» field specification
Returns:
  • «Aggregate»

Appends a new $project operator to this aggregate pipeline.

Mongoose query selection syntax is also supported.

Examples:

  1. // include a, include b, exclude _id
  2. aggregate.project("a b -_id");
  4. // or you may use object notation, useful when
  5. // you have keys already prefixed with a "-"
  6. aggregate.project({a: 1, b: 1, _id: 0});
  8. // reshaping documents
  9. aggregate.project({
  10.     newField: '$b.nested'
  11.   , plusTen: { $add: ['$val', 10]}
  12.   , sub: {
  13.        name: '$a'
  14.     }
  15. })
  17. // etc
  18. aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });

Aggregate.prototype.read()

Parameters

  • pref «String» one of the listed preference options or their aliases

  • [tags] «Array» optional tags for this query

Returns:
  • «Aggregate» this

Sets the readPreference option for the aggregation query.

Example:

  1. Model.aggregate(..).read('primaryPreferred').exec(callback)

Aggregate.prototype.readConcern()

Parameters
  • level «String» one of the listed read concern level or their aliases
Returns:
  • «Aggregate» this

Sets the readConcern level for the aggregation query.

Example:

  1. Model.aggregate(..).readConcern('majority').exec(callback)

Aggregate.prototype.redact()

Parameters

  • expression «Object» redact options or conditional expression

  • [thenExpr] «String|Object» true case for the condition

  • [elseExpr] «String|Object» false case for the condition

Returns:
  • «Aggregate» this

Appends a new $redact operator to this aggregate pipeline.

If 3 arguments are supplied, Mongoose will wrap them with if-then-else of $cond operator respectively If thenExpr or elseExpr is string, make sure it starts with , like DESCEND, PRUNE or KEEP.

Example:

  1. Model.aggregate(...)
  2.  .redact({
  3.    $cond: {
  4.      if: { $eq: [ '$level', 5 ] },
  5.      then: '$$PRUNE',
  6.      else: '$$DESCEND'
  7.    }
  8.  })
  9.  .exec();
  11. // $redact often comes with $cond operator, you can also use the following syntax provided by mongoose
  12. Model.aggregate(...)
  13.  .redact({ $eq: [ '$level', 5 ] }, '$$PRUNE', '$$DESCEND')
  14.  .exec();

Aggregate.prototype.replaceRoot()

Parameters
  • the «String|Object» field or document which will become the new root document
Returns:
  • «Aggregate»

Appends a new $replaceRoot operator to this aggregate pipeline.

Note that the $replaceRoot operator requires field strings to start with ‘$’. If you are passing in a string Mongoose will prepend ‘$’ if the specified field doesn’t start ‘$’. If you are passing in an object the strings in your expression will not be altered.

Examples:

  1. aggregate.replaceRoot("user");
  3. aggregate.replaceRoot({ x: { $concat: ['$this', '$that'] } });

Aggregate.prototype.sample()

Parameters
  • size «Number» number of random documents to pick
Returns:
  • «Aggregate»

Appends new custom $sample operator to this aggregate pipeline.

Examples:

  1. aggregate.sample(3); // Add a pipeline that picks 3 random documents

Aggregate.prototype.search()

Parameters
  • $search «Object» options
Returns:
  • «Aggregate» this

Helper for Atlas Text Search‘s $search stage.

Example:

  1. Model.aggregate().
  2.  search({
  3.    text: {
  4.      query: 'baseball',
  5.      path: 'plot'
  6.    }
  7.  });
  9. // Output: [{ plot: '...', title: '...' }]

Aggregate.prototype.session()

Parameters
  • session «ClientSession»

Sets the session for this aggregation. Useful for transactions.

Example:

  1. const session = await Model.startSession();
  2. await Model.aggregate(..).session(session);

Aggregate.prototype.skip()

Parameters
  • num «Number» number of records to skip before next stage
Returns:
  • «Aggregate»

Appends a new $skip operator to this aggregate pipeline.

Examples:

  1. aggregate.skip(10);

Aggregate.prototype.sort()

Parameters
  • arg «Object|String»
Returns:
  • «Aggregate» this

Appends a new $sort operator to this aggregate pipeline.

If an object is passed, values allowed are asc, desc, ascending, descending, 1, and -1.

If a string is passed, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with - which will be treated as descending.

Examples:

  1. // these are equivalent
  2. aggregate.sort({ field: 'asc', test: -1 });
  3. aggregate.sort('field -test');

Aggregate.prototype.sortByCount()

Parameters
  • arg «Object|String»
Returns:
  • «Aggregate» this

Appends a new $sortByCount operator to this aggregate pipeline. Accepts either a string field name or a pipeline object.

Note that the $sortByCount operator requires the new root to start with ‘$’. Mongoose will prepend ‘$’ if the specified field name doesn’t start with ‘$’.

Examples:

  1. aggregate.sortByCount('users');
  2. aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })

Aggregate.prototype.then()

Parameters

  • [resolve] «Function» successCallback

  • [reject] «Function» errorCallback

Returns:
  • «Promise»

Provides promise for aggregate.

Example:

  1. Model.aggregate(..).then(successCallback, errorCallback);

Aggregate.prototype.unwind()

Parameters
  • fields «String|Object» the field(s) to unwind, either as field names or as objects with options. If passing a string, prefixing the field name with ‘$’ is optional. If passing an object, path must start with ‘$’.
Returns:
  • «Aggregate»

Appends new custom $unwind operator(s) to this aggregate pipeline.

Note that the $unwind operator requires the path name to start with ‘$’. Mongoose will prepend ‘$’ if the specified field doesn’t start ‘$’.

Examples:

  1. aggregate.unwind("tags");
  2. aggregate.unwind("a", "b", "c");
  3. aggregate.unwind({ path: '$tags', preserveNullAndEmptyArrays: true });