Aggregate

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

Example:

const aggregate = Model.aggregate([ { $project: { a: 1, b: 1 } }, { $skip: 5 } ]); Model. aggregate([{ $match: { age: { $gte: 21 }}}]). unwind('tags'). exec();

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

  new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]); // Do this instead to cast to an ObjectId new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]);

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

Example:

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

Sets the allowDiskUse option for the aggregation query

Example:

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

Appends new operators to this aggregate pipeline

Example:

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

Executes the aggregation 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. Compatible with await.

Adds a collation

Example:

const res = await Model.aggregate(pipeline).collation({ locale: 'en_US', strength: 1 });

Appends a new $count operator to this aggregate pipeline.

Example:

aggregate.count("userCount");

Sets the cursor option and executes this aggregation, returning an aggregation cursor. Cursors are useful if you want to process the results of the aggregation one-at-a-time because the aggregation result is too big to fit into memory.

Example:

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

Appends a new $densify operator to this aggregate pipeline.

Example:

 aggregate.densify({ field: 'timestamp', range: { step: 1, unit: 'hour', bounds: [new Date('2021-05-18T00:00:00.000Z'), new Date('2021-05-18T08:00:00.000Z')] } });

Executes the aggregate pipeline on the currently bound Model.

Example:

const result = await aggregate.exec();

Execute the aggregation with explain

Example:

Model.aggregate(..).explain()

Combines multiple aggregation pipelines.

Example:

const res = await Model.aggregate().facet({ books: [{ groupBy: '$author' }], price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }] }); // Output: { books: [...], price: [{...}, {...}] }

Appends a new $fill operator to this aggregate pipeline.

Example:

 aggregate.fill({ output: { bootsSold: { value: 0 }, sandalsSold: { value: 0 }, sneakersSold: { value: 0 } } });

Executes the aggregate returning a Promise which will be resolved with .finally() chained.

More about Promise finally() in JavaScript.

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.

Example:

 // 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' }` 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

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

Example:

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

Sets the hint option for the aggregation query

Example:

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

Appends a new $limit operator to this aggregate pipeline.

Example:

aggregate.limit(10);

Appends new custom $lookup operator to this aggregate pipeline.

Example:

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

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

Example:

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

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

Example:

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

Appends a new $geoNear operator to this aggregate pipeline.

Note:

MUST be used as the first operator in the pipeline.

Example:

aggregate.near({ near: { type: 'Point', coordinates: [40.724, -73.997] }, distanceField: "dist.calculated", // required maxDistance: 0.008, query: { type: "public" }, includeLocs: "dist.location", spherical: true, });

Lets you set arbitrary options, for middleware or plugins.

Example:

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

Contains options passed down to the aggregate command. Supported options are:

• allowDiskUse
• bypassDocumentValidation
• collation
• comment
• cursor
• explain
• fieldsAsRaw
• hint
• let
• maxTimeMS
• raw
• readConcern
• readPreference
• session
• writeConcern

Returns the current pipeline

Example:

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

Appends a new $project operator to this aggregate pipeline.

Mongoose query selection syntax is also supported.

Example:

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

Sets the readPreference option for the aggregation query.

Example:

await Model.aggregate(pipeline).read('primaryPreferred');

Sets the readConcern level for the aggregation query.

Example:

await Model.aggregate(pipeline).readConcern('majority');

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:

await Model.aggregate(pipeline).redact({ $cond: { if: { $eq: [ '$level', 5 ] }, then: '$$PRUNE', else: '$$DESCEND' } }); // $redact often comes with $cond operator, you can also use the following syntax provided by mongoose await Model.aggregate(pipeline).redact({ $eq: [ '$level', 5 ] }, '$$PRUNE', '$$DESCEND');

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.

Example:

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

Appends new custom $sample operator to this aggregate pipeline.

Example:

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

Helper for Atlas Text Search's $search stage.

Example:

const res = await Model.aggregate(). search({ text: { query: 'baseball', path: 'plot' } }); // Output: [{ plot: '...', title: '...' }]

Sets the session for this aggregation. Useful for transactions.

Example:

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

Appends a new $skip operator to this aggregate pipeline.

Example:

aggregate.skip(10);

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.

Example:

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

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 '$'.

Example:

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

Provides a Promise-like then function, which will call .exec without a callback Compatible with await.

Example:

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

Appends new $unionWith operator to this aggregate pipeline.

Example:

aggregate.unionWith({ coll: 'users', pipeline: [ { $match: { _id: 1 } } ] });

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 '$'.

Example:

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

Returns an asyncIterator for use with for/await/of loops You do not need to call this function explicitly, the JavaScript runtime will call it for you.

Example:

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

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.