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. Creating an aggregation cursor runs pre aggregate hooks, but not post aggregate hooks. To skip pre aggregate hooks, pass middleware: false to .cursor().

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

Returns the current pipeline as a $unionWith-safe pipeline. Throws if this pipeline contains $out or $merge.

Example:

const base = MyModel.aggregate().match({ test: 1 });
base.pipelineForUnionWith(); // [{ $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

// `$match` before `$sample` samples from the filtered subset
aggregate.match({ difficulty: 'easy' }).sample(3);

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