deno.land / x / mongoose@6.7.5 / lib / aggregate.js
12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082108310841085108610871088108910901091109210931094109510961097109810991100110111021103110411051106110711081109111011111112111311141115111611171118111911201121112211231124112511261127112811291130113111321133113411351136113711381139114011411142114311441145114611471148114911501151115211531154115511561157115811591160116111621163116411651166'use strict';
/*! * Module dependencies */
const AggregationCursor = require('./cursor/AggregationCursor');const Query = require('./query');const { applyGlobalMaxTimeMS, applyGlobalDiskUse } = require('./helpers/query/applyGlobalOption');const getConstructorName = require('./helpers/getConstructorName');const prepareDiscriminatorPipeline = require('./helpers/aggregate/prepareDiscriminatorPipeline');const promiseOrCallback = require('./helpers/promiseOrCallback');const stringifyFunctionOperators = require('./helpers/aggregate/stringifyFunctionOperators');const utils = require('./utils');const read = Query.prototype.read;const readConcern = Query.prototype.readConcern;
const validRedactStringValues = new Set(['$$DESCEND', '$$PRUNE', '$$KEEP']);
/** * Aggregate constructor used for building aggregation pipelines. Do not * instantiate this class directly, use [Model.aggregate()](/docs/api.html#model_Model-aggregate) instead. * * #### Example: * * const aggregate = Model.aggregate([ * { $project: { a: 1, b: 1 } }, * { $skip: 5 } * ]); * * Model. * aggregate([{ $match: { age: { $gte: 21 }}}]). * unwind('tags'). * 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 * * new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]); * // Do this instead to cast to an ObjectId * new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]); * * @see MongoDB https://docs.mongodb.org/manual/applications/aggregation/ * @see driver https://mongodb.github.io/node-mongodb-native/4.9/classes/Collection.html#aggregate * @param {Array} [pipeline] aggregation pipeline as an array of objects * @param {Model} [model] the model to use with this aggregate. * @api public */
function Aggregate(pipeline, model) { this._pipeline = []; this._model = model; this.options = {};
if (arguments.length === 1 && Array.isArray(pipeline)) { this.append.apply(this, pipeline); }}
/** * Contains options passed down to the [aggregate command](https://docs.mongodb.com/manual/reference/command/aggregate/). * Supported options are: * * - [`allowDiskUse`](./api.html#aggregate_Aggregate-allowDiskUse) * - `bypassDocumentValidation` * - [`collation`](./api.html#aggregate_Aggregate-collation) * - `comment` * - [`cursor`](./api.html#aggregate_Aggregate-cursor) * - [`explain`](./api.html#aggregate_Aggregate-explain) * - `fieldsAsRaw` * - `hint` * - `let` * - `maxTimeMS` * - `raw` * - `readConcern` * - `readPreference` * - [`session`](./api.html#aggregate_Aggregate-session) * - `writeConcern` * * @property options * @memberOf Aggregate * @api public */
Aggregate.prototype.options;
/** * 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 * * @param {Model} [model] Set the model associated with this aggregate. If not provided, returns the already stored model. * @return {Model} * @api public */
Aggregate.prototype.model = function(model) { if (arguments.length === 0) { return this._model; }
this._model = model; if (model.schema != null) { if (this.options.readPreference == null && model.schema.options.read != null) { this.options.readPreference = model.schema.options.read; } if (this.options.collation == null && model.schema.options.collation != null) { this.options.collation = model.schema.options.collation; } }
return model;};
/** * 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); * * @param {...Object|Object[]} ops operator(s) to append. Can either be a spread of objects or a single parameter of a object array. * @return {Aggregate} * @api public */
Aggregate.prototype.append = function() { const args = (arguments.length === 1 && Array.isArray(arguments[0])) ? arguments[0] : [...arguments];
if (!args.every(isOperator)) { throw new Error('Arguments must be aggregate pipeline operators'); }
this._pipeline = this._pipeline.concat(args);
return this;};
/** * 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 ] } }); * * @param {Object} arg field specification * @see $addFields https://docs.mongodb.com/manual/reference/operator/aggregation/addFields/ * @return {Aggregate} * @api public */Aggregate.prototype.addFields = function(arg) { if (typeof arg !== 'object' || arg === null || Array.isArray(arg)) { throw new Error('Invalid addFields() argument. Must be an object'); } return this.append({ $addFields: Object.assign({}, arg) });};
/** * Appends a new $project operator to this aggregate pipeline. * * Mongoose query [selection syntax](#query_Query-select) 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 ] } }); * * @param {Object|String} arg field specification * @see projection https://docs.mongodb.org/manual/reference/aggregation/project/ * @return {Aggregate} * @api public */
Aggregate.prototype.project = function(arg) { const fields = {};
if (typeof arg === 'object' && !Array.isArray(arg)) { Object.keys(arg).forEach(function(field) { fields[field] = arg[field]; }); } else if (arguments.length === 1 && typeof arg === 'string') { arg.split(/\s+/).forEach(function(field) { if (!field) { return; } const include = field[0] === '-' ? 0 : 1; if (include === 0) { field = field.substring(1); } fields[field] = include; }); } else { throw new Error('Invalid project() argument. Must be string or object'); }
return this.append({ $project: fields });};
/** * Appends a new custom $group operator to this aggregate pipeline. * * #### Example: * * aggregate.group({ _id: "$department" }); * * @see $group https://docs.mongodb.org/manual/reference/aggregation/group/ * @method group * @memberOf Aggregate * @instance * @param {Object} arg $group operator contents * @return {Aggregate} * @api public */
/** * Appends a new custom $match operator to this aggregate pipeline. * * #### Example: * * aggregate.match({ department: { $in: [ "sales", "engineering" ] } }); * * @see $match https://docs.mongodb.org/manual/reference/aggregation/match/ * @method match * @memberOf Aggregate * @instance * @param {Object} arg $match operator contents * @return {Aggregate} * @api public */
/** * Appends a new $skip operator to this aggregate pipeline. * * #### Example: * * aggregate.skip(10); * * @see $skip https://docs.mongodb.org/manual/reference/aggregation/skip/ * @method skip * @memberOf Aggregate * @instance * @param {Number} num number of records to skip before next stage * @return {Aggregate} * @api public */
/** * Appends a new $limit operator to this aggregate pipeline. * * #### Example: * * aggregate.limit(10); * * @see $limit https://docs.mongodb.org/manual/reference/aggregation/limit/ * @method limit * @memberOf Aggregate * @instance * @param {Number} num maximum number of records to pass to the next stage * @return {Aggregate} * @api public */
/** * 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')] * } * }); * * @see $densify https://www.mongodb.com/docs/manual/reference/operator/aggregation/densify/ * @method densify * @memberOf Aggregate * @instance * @param {Object} arg $densify operator contents * @return {Aggregate} * @api public */
/** * Appends a new $fill operator to this aggregate pipeline. * * #### Example: * * aggregate.fill({ * output: { * bootsSold: { value: 0 }, * sandalsSold: { value: 0 }, * sneakersSold: { value: 0 } * } * }); * * @see $fill https://www.mongodb.com/docs/manual/reference/operator/aggregation/fill/ * @method fill * @memberOf Aggregate * @instance * @param {Object} arg $fill operator contents * @return {Aggregate} * @api public */
/** * Appends a new $geoNear operator to this aggregate pipeline. * * #### Note: * * **MUST** be used as the first operator in the pipeline. * * #### Example: * * aggregate.near({ * near: [40.724, -73.997], * distanceField: "dist.calculated", // required * maxDistance: 0.008, * query: { type: "public" }, * includeLocs: "dist.location", * uniqueDocs: true, * num: 5 * }); * * @see $geoNear https://docs.mongodb.org/manual/reference/aggregation/geoNear/ * @method near * @memberOf Aggregate * @instance * @param {Object} arg * @return {Aggregate} * @api public */
Aggregate.prototype.near = function(arg) { const op = {}; op.$geoNear = arg; return this.append(op);};
/*! * define methods */
'group match skip limit out densify fill'.split(' ').forEach(function($operator) { Aggregate.prototype[$operator] = function(arg) { const op = {}; op['$' + $operator] = arg; return this.append(op); };});
/** * 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 }); * * @see $unwind https://docs.mongodb.org/manual/reference/aggregation/unwind/ * @param {String|Object|String[]|Object[]} fields the field(s) to unwind, either as field names or as [objects with options](https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/#document-operand-with-options). If passing a string, prefixing the field name with '$' is optional. If passing an object, `path` must start with '$'. * @return {Aggregate} * @api public */
Aggregate.prototype.unwind = function() { const args = [...arguments];
const res = []; for (const arg of args) { if (arg && typeof arg === 'object') { res.push({ $unwind: arg }); } else if (typeof arg === 'string') { res.push({ $unwind: (arg[0] === '$') ? arg : '$' + arg }); } else { throw new Error('Invalid arg "' + arg + '" to unwind(), ' + 'must be string or object'); } }
return this.append.apply(this, res);};
/** * 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'] } }); * * @see $replaceRoot https://docs.mongodb.org/manual/reference/operator/aggregation/replaceRoot * @param {String|Object} newRoot the field or document which will become the new root document * @return {Aggregate} * @api public */
Aggregate.prototype.replaceRoot = function(newRoot) { let ret;
if (typeof newRoot === 'string') { ret = newRoot.startsWith('$') ? newRoot : '$' + newRoot; } else { ret = newRoot; }
return this.append({ $replaceRoot: { newRoot: ret } });};
/** * Appends a new $count operator to this aggregate pipeline. * * #### Example: * * aggregate.count("userCount"); * * @see $count https://docs.mongodb.org/manual/reference/operator/aggregation/count * @param {String} fieldName The name of the output field which has the count as its value. It must be a non-empty string, must not start with $ and must not contain the . character. * @return {Aggregate} * @api public */
Aggregate.prototype.count = function(fieldName) { return this.append({ $count: fieldName });};
/** * 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" ] }) * * @see $sortByCount https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/ * @param {Object|String} arg * @return {Aggregate} this * @api public */
Aggregate.prototype.sortByCount = function(arg) { if (arg && typeof arg === 'object') { return this.append({ $sortByCount: arg }); } else if (typeof arg === 'string') { return this.append({ $sortByCount: (arg[0] === '$') ? arg : '$' + arg }); } else { throw new TypeError('Invalid arg "' + arg + '" to sortByCount(), ' + 'must be string or object'); }};
/** * Appends new custom $lookup operator to this aggregate pipeline. * * #### Example: * * aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' }); * * @see $lookup https://docs.mongodb.org/manual/reference/operator/aggregation/lookup/#pipe._S_lookup * @param {Object} options to $lookup as described in the above link * @return {Aggregate} * @api public */
Aggregate.prototype.lookup = function(options) { return this.append({ $lookup: options });};
/** * 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 * * @see $graphLookup https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/#pipe._S_graphLookup * @param {Object} options to $graphLookup as described in the above link * @return {Aggregate} * @api public */
Aggregate.prototype.graphLookup = function(options) { const cloneOptions = {}; if (options) { if (!utils.isObject(options)) { throw new TypeError('Invalid graphLookup() argument. Must be an object.'); }
utils.mergeClone(cloneOptions, options); const startWith = cloneOptions.startWith;
if (startWith && typeof startWith === 'string') { cloneOptions.startWith = cloneOptions.startWith.startsWith('$') ? cloneOptions.startWith : '$' + cloneOptions.startWith; }
} return this.append({ $graphLookup: cloneOptions });};
/** * Appends new custom $sample operator to this aggregate pipeline. * * #### Example: * * aggregate.sample(3); // Add a pipeline that picks 3 random documents * * @see $sample https://docs.mongodb.org/manual/reference/operator/aggregation/sample/#pipe._S_sample * @param {Number} size number of random documents to pick * @return {Aggregate} * @api public */
Aggregate.prototype.sample = function(size) { return this.append({ $sample: { size: size } });};
/** * 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'); * * @see $sort https://docs.mongodb.org/manual/reference/aggregation/sort/ * @param {Object|String} arg * @return {Aggregate} this * @api public */
Aggregate.prototype.sort = function(arg) { // TODO refactor to reuse the query builder logic
const sort = {};
if (getConstructorName(arg) === 'Object') { const desc = ['desc', 'descending', -1]; Object.keys(arg).forEach(function(field) { // If sorting by text score, skip coercing into 1/-1 if (arg[field] instanceof Object && arg[field].$meta) { sort[field] = arg[field]; return; } sort[field] = desc.indexOf(arg[field]) === -1 ? 1 : -1; }); } else if (arguments.length === 1 && typeof arg === 'string') { arg.split(/\s+/).forEach(function(field) { if (!field) { return; } const ascend = field[0] === '-' ? -1 : 1; if (ascend === -1) { field = field.substring(1); } sort[field] = ascend; }); } else { throw new TypeError('Invalid sort() argument. Must be a string or object.'); }
return this.append({ $sort: sort });};
/** * Appends new $unionWith operator to this aggregate pipeline. * * #### Example: * * aggregate.unionWith({ coll: 'users', pipeline: [ { $match: { _id: 1 } } ] }); * * @see $unionWith https://docs.mongodb.com/manual/reference/operator/aggregation/unionWith * @param {Object} options to $unionWith query as described in the above link * @return {Aggregate} * @api public */
Aggregate.prototype.unionWith = function(options) { return this.append({ $unionWith: options });};
/** * Sets the readPreference option for the aggregation query. * * #### Example: * * await Model.aggregate(pipeline).read('primaryPreferred'); * * @param {String|ReadPreference} pref one of the listed preference options or their aliases * @param {Array} [tags] optional tags for this query. DEPRECATED * @return {Aggregate} this * @api public * @see mongodb https://docs.mongodb.org/manual/applications/replication/#read-preference */
Aggregate.prototype.read = function(pref, tags) { read.call(this, pref, tags); return this;};
/** * Sets the readConcern level for the aggregation query. * * #### Example: * * await Model.aggregate(pipeline).readConcern('majority'); * * @param {String} level one of the listed read concern level or their aliases * @see mongodb https://docs.mongodb.com/manual/reference/read-concern/ * @return {Aggregate} this * @api public */
Aggregate.prototype.readConcern = function(level) { readConcern.call(this, level); return 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: * * 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'); * * @param {Object} expression redact options or conditional expression * @param {String|Object} [thenExpr] true case for the condition * @param {String|Object} [elseExpr] false case for the condition * @return {Aggregate} this * @see $redact https://docs.mongodb.com/manual/reference/operator/aggregation/redact/ * @api public */
Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) { if (arguments.length === 3) { if ((typeof thenExpr === 'string' && !validRedactStringValues.has(thenExpr)) || (typeof elseExpr === 'string' && !validRedactStringValues.has(elseExpr))) { throw new Error('If thenExpr or elseExpr is string, it must be either $$DESCEND, $$PRUNE or $$KEEP'); }
expression = { $cond: { if: expression, then: thenExpr, else: elseExpr } }; } else if (arguments.length !== 1) { throw new TypeError('Invalid arguments'); }
return this.append({ $redact: expression });};
/** * Execute the aggregation with explain * * #### Example: * * Model.aggregate(..).explain(callback) * * @param {String} [verbosity] * @param {Function} [callback] The callback function to call, if not specified, will return a Promise instead. * @return {Promise} Returns a promise if no "callback" is given */
Aggregate.prototype.explain = function(verbosity, callback) { const model = this._model; if (typeof verbosity === 'function') { callback = verbosity; verbosity = null; }
return promiseOrCallback(callback, cb => { if (!this._pipeline.length) { const err = new Error('Aggregate has empty pipeline'); return cb(err); }
prepareDiscriminatorPipeline(this._pipeline, this._model.schema);
model.hooks.execPre('aggregate', this, error => { if (error) { const _opts = { error: error }; return model.hooks.execPost('aggregate', this, [null], _opts, error => { cb(error); }); }
model.collection.aggregate(this._pipeline, this.options, (error, cursor) => { if (error != null) { const _opts = { error: error }; return model.hooks.execPost('aggregate', this, [null], _opts, error => { cb(error); }); } if (verbosity != null) { cursor.explain(verbosity, (error, result) => { const _opts = { error: error }; return model.hooks.execPost('aggregate', this, [result], _opts, error => { if (error) { return cb(error); } return cb(null, result); }); }); } else { cursor.explain((error, result) => { const _opts = { error: error }; return model.hooks.execPost('aggregate', this, [result], _opts, error => { if (error) { return cb(error); } return cb(null, result); }); }); } }); }); }, model.events);};
/** * Sets the allowDiskUse option for the aggregation query * * #### Example: * * await Model.aggregate([{ $match: { foo: 'bar' } }]).allowDiskUse(true); * * @param {Boolean} value Should tell server it can use hard drive to store data during aggregation. * @return {Aggregate} this * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/ */
Aggregate.prototype.allowDiskUse = function(value) { this.options.allowDiskUse = value; return this;};
/** * Sets the hint option for the aggregation query * * #### Example: * * Model.aggregate(..).hint({ qty: 1, category: 1 }).exec(callback) * * @param {Object|String} value a hint object or the index name * @return {Aggregate} this * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/ */
Aggregate.prototype.hint = function(value) { this.options.hint = value; return this;};
/** * Sets the session for this aggregation. Useful for [transactions](/docs/transactions.html). * * #### Example: * * const session = await Model.startSession(); * await Model.aggregate(..).session(session); * * @param {ClientSession} session * @return {Aggregate} this * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/ */
Aggregate.prototype.session = function(session) { if (session == null) { delete this.options.session; } else { this.options.session = session; } return this;};
/** * 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 }` * * @param {Object} options keys to merge into current options * @param {Number} [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://docs.mongodb.com/manual/reference/operator/meta/maxTimeMS/) * @param {Boolean} [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation * @param {Object} [options.collation] object see [`Aggregate.prototype.collation()`](./docs/api.html#aggregate_Aggregate-collation) * @param {ClientSession} [options.session] ClientSession see [`Aggregate.prototype.session()`](./docs/api.html#aggregate_Aggregate-session) * @see mongodb https://docs.mongodb.org/manual/reference/command/aggregate/ * @return {Aggregate} this * @api public */
Aggregate.prototype.option = function(value) { for (const key in value) { this.options[key] = value[key]; } return this;};
/** * 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 * }); * * @param {Object} options * @param {Number} [options.batchSize] set the cursor batch size * @param {Boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics) * @return {AggregationCursor} cursor representing this aggregation * @api public * @see mongodb https://mongodb.github.io/node-mongodb-native/4.9/classes/AggregationCursor.html */
Aggregate.prototype.cursor = function(options) { this.options.cursor = options || {}; return new AggregationCursor(this); // return this;};
/** * Adds a collation * * #### Example: * * const res = await Model.aggregate(pipeline).collation({ locale: 'en_US', strength: 1 }); * * @param {Object} collation options * @return {Aggregate} this * @api public * @see mongodb https://mongodb.github.io/node-mongodb-native/4.9/interfaces/CollationOptions.html */
Aggregate.prototype.collation = function(collation) { this.options.collation = collation; return this;};
/** * Combines multiple aggregation pipelines. * * #### Example: * * const res = await Model.aggregate().facet({ * books: [{ groupBy: '$author' }], * price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }] * }); * * // Output: { books: [...], price: [{...}, {...}] } * * @param {Object} facet options * @return {Aggregate} this * @see $facet https://docs.mongodb.com/v3.4/reference/operator/aggregation/facet/ * @api public */
Aggregate.prototype.facet = function(options) { return this.append({ $facet: options });};
/** * Helper for [Atlas Text Search](https://docs.atlas.mongodb.com/reference/atlas-search/tutorial/)'s * `$search` stage. * * #### Example: * * const res = await Model.aggregate(). * search({ * text: { * query: 'baseball', * path: 'plot' * } * }); * * // Output: [{ plot: '...', title: '...' }] * * @param {Object} $search options * @return {Aggregate} this * @see $search https://docs.atlas.mongodb.com/reference/atlas-search/tutorial/ * @api public */
Aggregate.prototype.search = function(options) { return this.append({ $search: options });};
/** * Returns the current pipeline * * #### Example: * * MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }] * * @return {Array} The current pipeline similar to the operation that will be executed * @api public */
Aggregate.prototype.pipeline = function() { return this._pipeline;};
/** * Executes the aggregate pipeline on the currently bound Model. * * #### Example: * * aggregate.exec(callback); * * // Because a promise is returned, the `callback` is optional. * const result = await aggregate.exec(); * * @param {Function} [callback] * @return {Promise} Returns a Promise if no "callback" is given. * @api public */
Aggregate.prototype.exec = function(callback) { if (!this._model) { throw new Error('Aggregate not bound to any Model'); } const model = this._model; const collection = this._model.collection;
applyGlobalMaxTimeMS(this.options, model); applyGlobalDiskUse(this.options, model);
if (this.options && this.options.cursor) { return new AggregationCursor(this); }
return promiseOrCallback(callback, cb => { prepareDiscriminatorPipeline(this._pipeline, this._model.schema); stringifyFunctionOperators(this._pipeline);
model.hooks.execPre('aggregate', this, error => { if (error) { const _opts = { error: error }; return model.hooks.execPost('aggregate', this, [null], _opts, error => { cb(error); }); } if (!this._pipeline.length) { return cb(new Error('Aggregate has empty pipeline')); }
const options = utils.clone(this.options || {});
collection.aggregate(this._pipeline, options, (err, cursor) => { if (err != null) { return cb(err); }
cursor.toArray((error, result) => { const _opts = { error: error }; model.hooks.execPost('aggregate', this, [result], _opts, (error, result) => { if (error) { return cb(error); }
cb(null, result); }); }); }); }); }, model.events);};
/** * Provides a Promise-like `then` function, which will call `.exec` without a callback * Compatible with `await`. * * #### Example: * * Model.aggregate(..).then(successCallback, errorCallback); * * @param {Function} [resolve] successCallback * @param {Function} [reject] errorCallback * @return {Promise} */Aggregate.prototype.then = function(resolve, reject) { return this.exec().then(resolve, reject);};
/** * Executes the query returning a `Promise` which will be * resolved with either the doc(s) or rejected with the error. * Like [`.then()`](#query_Query-then), but only takes a rejection handler. * Compatible with `await`. * * @param {Function} [reject] * @return {Promise} * @api public */
Aggregate.prototype.catch = function(reject) { return this.exec().then(null, reject);};
/** * 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: * * 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](https://github.com/tc39/proposal-async-iteration/issues/117#issuecomment-346695187). * * **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. * * @method Symbol.asyncIterator * @memberOf Aggregate * @instance * @api public */
if (Symbol.asyncIterator != null) { Aggregate.prototype[Symbol.asyncIterator] = function() { return this.cursor({ useMongooseAggCursor: true }).transformNull()._transformForAsyncIterator(); };}
/*! * Helpers */
/** * Checks whether an object is likely a pipeline operator * * @param {Object} obj object to check * @return {Boolean} * @api private */
function isOperator(obj) { if (typeof obj !== 'object' || obj === null) { return false; }
const k = Object.keys(obj);
return k.length === 1 && k[0][0] === '$';}
/** * Adds the appropriate `$match` pipeline step to the top of an aggregate's * pipeline, should it's model is a non-root discriminator type. This is * analogous to the `prepareDiscriminatorCriteria` function in `lib/query.js`. * * @param {Aggregate} aggregate Aggregate to prepare * @api private */
Aggregate._prepareDiscriminatorPipeline = prepareDiscriminatorPipeline;
/*! * Exports */
module.exports = Aggregate;
Version Info