Ohm-Management - Projektarbeit B-ME
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

aggregate.js 31KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111
  1. 'use strict';
  2. /*!
  3. * Module dependencies
  4. */
  5. const AggregationCursor = require('./cursor/AggregationCursor');
  6. const Query = require('./query');
  7. const util = require('util');
  8. const utils = require('./utils');
  9. const read = Query.prototype.read;
  10. const readConcern = Query.prototype.readConcern;
  11. /**
  12. * Aggregate constructor used for building aggregation pipelines. Do not
  13. * instantiate this class directly, use [Model.aggregate()](/docs/api.html#model_Model.aggregate) instead.
  14. *
  15. * ####Example:
  16. *
  17. * const aggregate = Model.aggregate([
  18. * { $project: { a: 1, b: 1 } },
  19. * { $skip: 5 }
  20. * ]);
  21. *
  22. * Model.
  23. * aggregate([{ $match: { age: { $gte: 21 }}}]).
  24. * unwind('tags').
  25. * exec(callback);
  26. *
  27. * ####Note:
  28. *
  29. * - The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
  30. * - Mongoose does **not** cast pipeline stages. The below will **not** work unless `_id` is a string in the database
  31. *
  32. * ```javascript
  33. * new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]);
  34. * // Do this instead to cast to an ObjectId
  35. * new Aggregate([{ $match: { _id: mongoose.Types.ObjectId('00000000000000000000000a') } }]);
  36. * ```
  37. *
  38. * @see MongoDB http://docs.mongodb.org/manual/applications/aggregation/
  39. * @see driver http://mongodb.github.com/node-mongodb-native/api-generated/collection.html#aggregate
  40. * @param {Array} [pipeline] aggregation pipeline as an array of objects
  41. * @api public
  42. */
  43. function Aggregate(pipeline) {
  44. this._pipeline = [];
  45. this._model = undefined;
  46. this.options = {};
  47. if (arguments.length === 1 && util.isArray(pipeline)) {
  48. this.append.apply(this, pipeline);
  49. }
  50. }
  51. /**
  52. * Contains options passed down to the [aggregate command](https://docs.mongodb.com/manual/reference/command/aggregate/).
  53. * Supported options are:
  54. *
  55. * - `readPreference`
  56. * - [`cursor`](./api.html#aggregate_Aggregate-cursor)
  57. * - [`explain`](./api.html#aggregate_Aggregate-explain)
  58. * - [`allowDiskUse`](./api.html#aggregate_Aggregate-allowDiskUse)
  59. * - `maxTimeMS`
  60. * - `bypassDocumentValidation`
  61. * - `raw`
  62. * - `promoteLongs`
  63. * - `promoteValues`
  64. * - `promoteBuffers`
  65. * - [`collation`](./api.html#aggregate_Aggregate-collation)
  66. * - `comment`
  67. * - [`session`](./api.html#aggregate_Aggregate-session)
  68. *
  69. * @property options
  70. * @memberOf Aggregate
  71. * @api public
  72. */
  73. Aggregate.prototype.options;
  74. /**
  75. * Get/set the model that this aggregation will execute on.
  76. *
  77. * ####Example:
  78. * const aggregate = MyModel.aggregate([{ $match: { answer: 42 } }]);
  79. * aggregate.model() === MyModel; // true
  80. *
  81. * // Change the model. There's rarely any reason to do this.
  82. * aggregate.model(SomeOtherModel);
  83. * aggregate.model() === SomeOtherModel; // true
  84. *
  85. * @param {Model} [model] the model to which the aggregate is to be bound
  86. * @return {Aggregate|Model} if model is passed, will return `this`, otherwise will return the model
  87. * @api public
  88. */
  89. Aggregate.prototype.model = function(model) {
  90. if (arguments.length === 0) {
  91. return this._model;
  92. }
  93. this._model = model;
  94. if (model.schema != null) {
  95. if (this.options.readPreference == null &&
  96. model.schema.options.read != null) {
  97. this.options.readPreference = model.schema.options.read;
  98. }
  99. if (this.options.collation == null &&
  100. model.schema.options.collation != null) {
  101. this.options.collation = model.schema.options.collation;
  102. }
  103. }
  104. return this;
  105. };
  106. /**
  107. * Appends new operators to this aggregate pipeline
  108. *
  109. * ####Examples:
  110. *
  111. * aggregate.append({ $project: { field: 1 }}, { $limit: 2 });
  112. *
  113. * // or pass an array
  114. * var pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
  115. * aggregate.append(pipeline);
  116. *
  117. * @param {Object} ops operator(s) to append
  118. * @return {Aggregate}
  119. * @api public
  120. */
  121. Aggregate.prototype.append = function() {
  122. const args = (arguments.length === 1 && util.isArray(arguments[0]))
  123. ? arguments[0]
  124. : utils.args(arguments);
  125. if (!args.every(isOperator)) {
  126. throw new Error('Arguments must be aggregate pipeline operators');
  127. }
  128. this._pipeline = this._pipeline.concat(args);
  129. return this;
  130. };
  131. /**
  132. * Appends a new $addFields operator to this aggregate pipeline.
  133. * Requires MongoDB v3.4+ to work
  134. *
  135. * ####Examples:
  136. *
  137. * // adding new fields based on existing fields
  138. * aggregate.addFields({
  139. * newField: '$b.nested'
  140. * , plusTen: { $add: ['$val', 10]}
  141. * , sub: {
  142. * name: '$a'
  143. * }
  144. * })
  145. *
  146. * // etc
  147. * aggregate.addFields({ salary_k: { $divide: [ "$salary", 1000 ] } });
  148. *
  149. * @param {Object} arg field specification
  150. * @see $addFields https://docs.mongodb.com/manual/reference/operator/aggregation/addFields/
  151. * @return {Aggregate}
  152. * @api public
  153. */
  154. Aggregate.prototype.addFields = function(arg) {
  155. const fields = {};
  156. if (typeof arg === 'object' && !util.isArray(arg)) {
  157. Object.keys(arg).forEach(function(field) {
  158. fields[field] = arg[field];
  159. });
  160. } else {
  161. throw new Error('Invalid addFields() argument. Must be an object');
  162. }
  163. return this.append({$addFields: fields});
  164. };
  165. /**
  166. * Appends a new $project operator to this aggregate pipeline.
  167. *
  168. * Mongoose query [selection syntax](#query_Query-select) is also supported.
  169. *
  170. * ####Examples:
  171. *
  172. * // include a, include b, exclude _id
  173. * aggregate.project("a b -_id");
  174. *
  175. * // or you may use object notation, useful when
  176. * // you have keys already prefixed with a "-"
  177. * aggregate.project({a: 1, b: 1, _id: 0});
  178. *
  179. * // reshaping documents
  180. * aggregate.project({
  181. * newField: '$b.nested'
  182. * , plusTen: { $add: ['$val', 10]}
  183. * , sub: {
  184. * name: '$a'
  185. * }
  186. * })
  187. *
  188. * // etc
  189. * aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });
  190. *
  191. * @param {Object|String} arg field specification
  192. * @see projection http://docs.mongodb.org/manual/reference/aggregation/project/
  193. * @return {Aggregate}
  194. * @api public
  195. */
  196. Aggregate.prototype.project = function(arg) {
  197. const fields = {};
  198. if (typeof arg === 'object' && !util.isArray(arg)) {
  199. Object.keys(arg).forEach(function(field) {
  200. fields[field] = arg[field];
  201. });
  202. } else if (arguments.length === 1 && typeof arg === 'string') {
  203. arg.split(/\s+/).forEach(function(field) {
  204. if (!field) {
  205. return;
  206. }
  207. const include = field[0] === '-' ? 0 : 1;
  208. if (include === 0) {
  209. field = field.substring(1);
  210. }
  211. fields[field] = include;
  212. });
  213. } else {
  214. throw new Error('Invalid project() argument. Must be string or object');
  215. }
  216. return this.append({$project: fields});
  217. };
  218. /**
  219. * Appends a new custom $group operator to this aggregate pipeline.
  220. *
  221. * ####Examples:
  222. *
  223. * aggregate.group({ _id: "$department" });
  224. *
  225. * @see $group http://docs.mongodb.org/manual/reference/aggregation/group/
  226. * @method group
  227. * @memberOf Aggregate
  228. * @instance
  229. * @param {Object} arg $group operator contents
  230. * @return {Aggregate}
  231. * @api public
  232. */
  233. /**
  234. * Appends a new custom $match operator to this aggregate pipeline.
  235. *
  236. * ####Examples:
  237. *
  238. * aggregate.match({ department: { $in: [ "sales", "engineering" ] } });
  239. *
  240. * @see $match http://docs.mongodb.org/manual/reference/aggregation/match/
  241. * @method match
  242. * @memberOf Aggregate
  243. * @instance
  244. * @param {Object} arg $match operator contents
  245. * @return {Aggregate}
  246. * @api public
  247. */
  248. /**
  249. * Appends a new $skip operator to this aggregate pipeline.
  250. *
  251. * ####Examples:
  252. *
  253. * aggregate.skip(10);
  254. *
  255. * @see $skip http://docs.mongodb.org/manual/reference/aggregation/skip/
  256. * @method skip
  257. * @memberOf Aggregate
  258. * @instance
  259. * @param {Number} num number of records to skip before next stage
  260. * @return {Aggregate}
  261. * @api public
  262. */
  263. /**
  264. * Appends a new $limit operator to this aggregate pipeline.
  265. *
  266. * ####Examples:
  267. *
  268. * aggregate.limit(10);
  269. *
  270. * @see $limit http://docs.mongodb.org/manual/reference/aggregation/limit/
  271. * @method limit
  272. * @memberOf Aggregate
  273. * @instance
  274. * @param {Number} num maximum number of records to pass to the next stage
  275. * @return {Aggregate}
  276. * @api public
  277. */
  278. /**
  279. * Appends a new $geoNear operator to this aggregate pipeline.
  280. *
  281. * ####NOTE:
  282. *
  283. * **MUST** be used as the first operator in the pipeline.
  284. *
  285. * ####Examples:
  286. *
  287. * aggregate.near({
  288. * near: [40.724, -73.997],
  289. * distanceField: "dist.calculated", // required
  290. * maxDistance: 0.008,
  291. * query: { type: "public" },
  292. * includeLocs: "dist.location",
  293. * uniqueDocs: true,
  294. * num: 5
  295. * });
  296. *
  297. * @see $geoNear http://docs.mongodb.org/manual/reference/aggregation/geoNear/
  298. * @method near
  299. * @memberOf Aggregate
  300. * @instance
  301. * @param {Object} arg
  302. * @return {Aggregate}
  303. * @api public
  304. */
  305. Aggregate.prototype.near = function(arg) {
  306. const op = {};
  307. op.$geoNear = arg;
  308. return this.append(op);
  309. };
  310. /*!
  311. * define methods
  312. */
  313. 'group match skip limit out'.split(' ').forEach(function($operator) {
  314. Aggregate.prototype[$operator] = function(arg) {
  315. const op = {};
  316. op['$' + $operator] = arg;
  317. return this.append(op);
  318. };
  319. });
  320. /**
  321. * Appends new custom $unwind operator(s) to this aggregate pipeline.
  322. *
  323. * Note that the `$unwind` operator requires the path name to start with '$'.
  324. * Mongoose will prepend '$' if the specified field doesn't start '$'.
  325. *
  326. * ####Examples:
  327. *
  328. * aggregate.unwind("tags");
  329. * aggregate.unwind("a", "b", "c");
  330. *
  331. * @see $unwind http://docs.mongodb.org/manual/reference/aggregation/unwind/
  332. * @param {String} fields the field(s) to unwind
  333. * @return {Aggregate}
  334. * @api public
  335. */
  336. Aggregate.prototype.unwind = function() {
  337. const args = utils.args(arguments);
  338. const res = [];
  339. for (let i = 0; i < args.length; ++i) {
  340. const arg = args[i];
  341. if (arg && typeof arg === 'object') {
  342. res.push({ $unwind: arg });
  343. } else if (typeof arg === 'string') {
  344. res.push({
  345. $unwind: (arg && arg.charAt(0) === '$') ? arg : '$' + arg
  346. });
  347. } else {
  348. throw new Error('Invalid arg "' + arg + '" to unwind(), ' +
  349. 'must be string or object');
  350. }
  351. }
  352. return this.append.apply(this, res);
  353. };
  354. /**
  355. * Appends a new $replaceRoot operator to this aggregate pipeline.
  356. *
  357. * Note that the `$replaceRoot` operator requires field strings to start with '$'.
  358. * If you are passing in a string Mongoose will prepend '$' if the specified field doesn't start '$'.
  359. * If you are passing in an object the strings in your expression will not be altered.
  360. *
  361. * ####Examples:
  362. *
  363. * aggregate.replaceRoot("user");
  364. *
  365. * aggregate.replaceRoot({ x: { $concat: ['$this', '$that'] } });
  366. *
  367. * @see $replaceRoot https://docs.mongodb.org/manual/reference/operator/aggregation/replaceRoot
  368. * @param {String|Object} the field or document which will become the new root document
  369. * @return {Aggregate}
  370. * @api public
  371. */
  372. Aggregate.prototype.replaceRoot = function(newRoot) {
  373. let ret;
  374. if (typeof newRoot === 'string') {
  375. ret = newRoot.startsWith('$') ? newRoot : '$' + newRoot;
  376. } else {
  377. ret = newRoot;
  378. }
  379. return this.append({
  380. $replaceRoot: {
  381. newRoot: ret
  382. }
  383. });
  384. };
  385. /**
  386. * Appends a new $count operator to this aggregate pipeline.
  387. *
  388. * ####Examples:
  389. *
  390. * aggregate.count("userCount");
  391. *
  392. * @see $count https://docs.mongodb.org/manual/reference/operator/aggregation/count
  393. * @param {String} the name of the count field
  394. * @return {Aggregate}
  395. * @api public
  396. */
  397. Aggregate.prototype.count = function(countName) {
  398. return this.append({ $count: countName });
  399. };
  400. /**
  401. * Appends a new $sortByCount operator to this aggregate pipeline. Accepts either a string field name
  402. * or a pipeline object.
  403. *
  404. * Note that the `$sortByCount` operator requires the new root to start with '$'.
  405. * Mongoose will prepend '$' if the specified field name doesn't start with '$'.
  406. *
  407. * ####Examples:
  408. *
  409. * aggregate.sortByCount('users');
  410. * aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })
  411. *
  412. * @see $sortByCount https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/
  413. * @param {Object|String} arg
  414. * @return {Aggregate} this
  415. * @api public
  416. */
  417. Aggregate.prototype.sortByCount = function(arg) {
  418. if (arg && typeof arg === 'object') {
  419. return this.append({ $sortByCount: arg });
  420. } else if (typeof arg === 'string') {
  421. return this.append({
  422. $sortByCount: (arg && arg.charAt(0) === '$') ? arg : '$' + arg
  423. });
  424. } else {
  425. throw new TypeError('Invalid arg "' + arg + '" to sortByCount(), ' +
  426. 'must be string or object');
  427. }
  428. };
  429. /**
  430. * Appends new custom $lookup operator(s) to this aggregate pipeline.
  431. *
  432. * ####Examples:
  433. *
  434. * aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });
  435. *
  436. * @see $lookup https://docs.mongodb.org/manual/reference/operator/aggregation/lookup/#pipe._S_lookup
  437. * @param {Object} options to $lookup as described in the above link
  438. * @return {Aggregate}
  439. * @api public
  440. */
  441. Aggregate.prototype.lookup = function(options) {
  442. return this.append({$lookup: options});
  443. };
  444. /**
  445. * Appends new custom $graphLookup operator(s) to this aggregate pipeline, performing a recursive search on a collection.
  446. *
  447. * Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if `{ allowDiskUse: true }` is specified.
  448. *
  449. * #### Examples:
  450. * // 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' }`
  451. * 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
  452. *
  453. * @see $graphLookup https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/#pipe._S_graphLookup
  454. * @param {Object} options to $graphLookup as described in the above link
  455. * @return {Aggregate}
  456. * @api public
  457. */
  458. Aggregate.prototype.graphLookup = function(options) {
  459. const cloneOptions = {};
  460. if (options) {
  461. if (!utils.isObject(options)) {
  462. throw new TypeError('Invalid graphLookup() argument. Must be an object.');
  463. }
  464. utils.mergeClone(cloneOptions, options);
  465. const startWith = cloneOptions.startWith;
  466. if (startWith && typeof startWith === 'string') {
  467. cloneOptions.startWith = cloneOptions.startWith.charAt(0) === '$' ?
  468. cloneOptions.startWith :
  469. '$' + cloneOptions.startWith;
  470. }
  471. }
  472. return this.append({ $graphLookup: cloneOptions });
  473. };
  474. /**
  475. * Appends new custom $sample operator(s) to this aggregate pipeline.
  476. *
  477. * ####Examples:
  478. *
  479. * aggregate.sample(3); // Add a pipeline that picks 3 random documents
  480. *
  481. * @see $sample https://docs.mongodb.org/manual/reference/operator/aggregation/sample/#pipe._S_sample
  482. * @param {Number} size number of random documents to pick
  483. * @return {Aggregate}
  484. * @api public
  485. */
  486. Aggregate.prototype.sample = function(size) {
  487. return this.append({$sample: {size: size}});
  488. };
  489. /**
  490. * Appends a new $sort operator to this aggregate pipeline.
  491. *
  492. * If an object is passed, values allowed are `asc`, `desc`, `ascending`, `descending`, `1`, and `-1`.
  493. *
  494. * 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.
  495. *
  496. * ####Examples:
  497. *
  498. * // these are equivalent
  499. * aggregate.sort({ field: 'asc', test: -1 });
  500. * aggregate.sort('field -test');
  501. *
  502. * @see $sort http://docs.mongodb.org/manual/reference/aggregation/sort/
  503. * @param {Object|String} arg
  504. * @return {Aggregate} this
  505. * @api public
  506. */
  507. Aggregate.prototype.sort = function(arg) {
  508. // TODO refactor to reuse the query builder logic
  509. const sort = {};
  510. if (arg.constructor.name === 'Object') {
  511. const desc = ['desc', 'descending', -1];
  512. Object.keys(arg).forEach(function(field) {
  513. // If sorting by text score, skip coercing into 1/-1
  514. if (arg[field] instanceof Object && arg[field].$meta) {
  515. sort[field] = arg[field];
  516. return;
  517. }
  518. sort[field] = desc.indexOf(arg[field]) === -1 ? 1 : -1;
  519. });
  520. } else if (arguments.length === 1 && typeof arg === 'string') {
  521. arg.split(/\s+/).forEach(function(field) {
  522. if (!field) {
  523. return;
  524. }
  525. const ascend = field[0] === '-' ? -1 : 1;
  526. if (ascend === -1) {
  527. field = field.substring(1);
  528. }
  529. sort[field] = ascend;
  530. });
  531. } else {
  532. throw new TypeError('Invalid sort() argument. Must be a string or object.');
  533. }
  534. return this.append({$sort: sort});
  535. };
  536. /**
  537. * Sets the readPreference option for the aggregation query.
  538. *
  539. * ####Example:
  540. *
  541. * Model.aggregate(..).read('primaryPreferred').exec(callback)
  542. *
  543. * @param {String} pref one of the listed preference options or their aliases
  544. * @param {Array} [tags] optional tags for this query
  545. * @return {Aggregate} this
  546. * @api public
  547. * @see mongodb http://docs.mongodb.org/manual/applications/replication/#read-preference
  548. * @see driver http://mongodb.github.com/node-mongodb-native/driver-articles/anintroductionto1_1and2_2.html#read-preferences
  549. */
  550. Aggregate.prototype.read = function(pref, tags) {
  551. if (!this.options) {
  552. this.options = {};
  553. }
  554. read.call(this, pref, tags);
  555. return this;
  556. };
  557. /**
  558. * Sets the readConcern level for the aggregation query.
  559. *
  560. * ####Example:
  561. *
  562. * Model.aggregate(..).readConcern('majority').exec(callback)
  563. *
  564. * @param {String} level one of the listed read concern level or their aliases
  565. * @see mongodb https://docs.mongodb.com/manual/reference/read-concern/
  566. * @return {Aggregate} this
  567. * @api public
  568. */
  569. Aggregate.prototype.readConcern = function(level) {
  570. if (!this.options) {
  571. this.options = {};
  572. }
  573. readConcern.call(this, level);
  574. return this;
  575. };
  576. /**
  577. * Appends a new $redact operator to this aggregate pipeline.
  578. *
  579. * If 3 arguments are supplied, Mongoose will wrap them with if-then-else of $cond operator respectively
  580. * If `thenExpr` or `elseExpr` is string, make sure it starts with $$, like `$$DESCEND`, `$$PRUNE` or `$$KEEP`.
  581. *
  582. * ####Example:
  583. *
  584. * Model.aggregate(...)
  585. * .redact({
  586. * $cond: {
  587. * if: { $eq: [ '$level', 5 ] },
  588. * then: '$$PRUNE',
  589. * else: '$$DESCEND'
  590. * }
  591. * })
  592. * .exec();
  593. *
  594. * // $redact often comes with $cond operator, you can also use the following syntax provided by mongoose
  595. * Model.aggregate(...)
  596. * .redact({ $eq: [ '$level', 5 ] }, '$$PRUNE', '$$DESCEND')
  597. * .exec();
  598. *
  599. * @param {Object} expression redact options or conditional expression
  600. * @param {String|Object} [thenExpr] true case for the condition
  601. * @param {String|Object} [elseExpr] false case for the condition
  602. * @return {Aggregate} this
  603. * @see $redact https://docs.mongodb.com/manual/reference/operator/aggregation/redact/
  604. * @api public
  605. */
  606. Aggregate.prototype.redact = function(expression, thenExpr, elseExpr) {
  607. if (arguments.length === 3) {
  608. if ((typeof thenExpr === 'string' && !thenExpr.startsWith('$$')) ||
  609. (typeof elseExpr === 'string' && !elseExpr.startsWith('$$'))) {
  610. throw new Error('If thenExpr or elseExpr is string, it must start with $$. e.g. $$DESCEND, $$PRUNE, $$KEEP');
  611. }
  612. expression = {
  613. $cond: {
  614. if: expression,
  615. then: thenExpr,
  616. else: elseExpr
  617. }
  618. };
  619. } else if (arguments.length !== 1) {
  620. throw new TypeError('Invalid arguments');
  621. }
  622. return this.append({$redact: expression});
  623. };
  624. /**
  625. * Execute the aggregation with explain
  626. *
  627. * ####Example:
  628. *
  629. * Model.aggregate(..).explain(callback)
  630. *
  631. * @param {Function} callback
  632. * @return {Promise}
  633. */
  634. Aggregate.prototype.explain = function(callback) {
  635. return utils.promiseOrCallback(callback, cb => {
  636. if (!this._pipeline.length) {
  637. const err = new Error('Aggregate has empty pipeline');
  638. return cb(err);
  639. }
  640. prepareDiscriminatorPipeline(this);
  641. this._model.collection.
  642. aggregate(this._pipeline, this.options || {}).
  643. explain(function(error, result) {
  644. if (error) {
  645. return cb(error);
  646. }
  647. cb(null, result);
  648. });
  649. }, this._model.events);
  650. };
  651. /**
  652. * Sets the allowDiskUse option for the aggregation query (ignored for < 2.6.0)
  653. *
  654. * ####Example:
  655. *
  656. * await Model.aggregate([{ $match: { foo: 'bar' } }]).allowDiskUse(true);
  657. *
  658. * @param {Boolean} value Should tell server it can use hard drive to store data during aggregation.
  659. * @param {Array} [tags] optional tags for this query
  660. * @see mongodb http://docs.mongodb.org/manual/reference/command/aggregate/
  661. */
  662. Aggregate.prototype.allowDiskUse = function(value) {
  663. this.options.allowDiskUse = value;
  664. return this;
  665. };
  666. /**
  667. * Sets the hint option for the aggregation query (ignored for < 3.6.0)
  668. *
  669. * ####Example:
  670. *
  671. * Model.aggregate(..).hint({ qty: 1, category: 1 }).exec(callback)
  672. *
  673. * @param {Object|String} value a hint object or the index name
  674. * @see mongodb http://docs.mongodb.org/manual/reference/command/aggregate/
  675. */
  676. Aggregate.prototype.hint = function(value) {
  677. this.options.hint = value;
  678. return this;
  679. };
  680. /**
  681. * Sets the session for this aggregation. Useful for [transactions](/docs/transactions.html).
  682. *
  683. * ####Example:
  684. *
  685. * const session = await Model.startSession();
  686. * await Model.aggregate(..).session(session);
  687. *
  688. * @param {ClientSession} session
  689. * @see mongodb http://docs.mongodb.org/manual/reference/command/aggregate/
  690. */
  691. Aggregate.prototype.session = function(session) {
  692. if (session == null) {
  693. delete this.options.session;
  694. } else {
  695. this.options.session = session;
  696. }
  697. return this;
  698. };
  699. /**
  700. * Lets you set arbitrary options, for middleware or plugins.
  701. *
  702. * ####Example:
  703. *
  704. * var agg = Model.aggregate(..).option({ allowDiskUse: true }); // Set the `allowDiskUse` option
  705. * agg.options; // `{ allowDiskUse: true }`
  706. *
  707. * @param {Object} options keys to merge into current options
  708. * @param [options.maxTimeMS] number limits the time this aggregation will run, see [MongoDB docs on `maxTimeMS`](https://docs.mongodb.com/manual/reference/operator/meta/maxTimeMS/)
  709. * @param [options.allowDiskUse] boolean if true, the MongoDB server will use the hard drive to store data during this aggregation
  710. * @param [options.collation] object see [`Aggregate.prototype.collation()`](./docs/api.html#aggregate_Aggregate-collation)
  711. * @param [options.session] ClientSession see [`Aggregate.prototype.session()`](./docs/api.html#aggregate_Aggregate-session)
  712. * @see mongodb http://docs.mongodb.org/manual/reference/command/aggregate/
  713. * @return {Aggregate} this
  714. * @api public
  715. */
  716. Aggregate.prototype.option = function(value) {
  717. for (const key in value) {
  718. this.options[key] = value[key];
  719. }
  720. return this;
  721. };
  722. /**
  723. * Sets the cursor option option for the aggregation query (ignored for < 2.6.0).
  724. * Note the different syntax below: .exec() returns a cursor object, and no callback
  725. * is necessary.
  726. *
  727. * ####Example:
  728. *
  729. * var cursor = Model.aggregate(..).cursor({ batchSize: 1000 }).exec();
  730. * cursor.eachAsync(function(error, doc) {
  731. * // use doc
  732. * });
  733. *
  734. * @param {Object} options
  735. * @param {Number} options.batchSize set the cursor batch size
  736. * @param {Boolean} [options.useMongooseAggCursor] use experimental mongoose-specific aggregation cursor (for `eachAsync()` and other query cursor semantics)
  737. * @return {Aggregate} this
  738. * @api public
  739. * @see mongodb http://mongodb.github.io/node-mongodb-native/2.0/api/AggregationCursor.html
  740. */
  741. Aggregate.prototype.cursor = function(options) {
  742. if (!this.options) {
  743. this.options = {};
  744. }
  745. this.options.cursor = options || {};
  746. return this;
  747. };
  748. /**
  749. * Sets an option on this aggregation. This function will be deprecated in a
  750. * future release. Use the [`cursor()`](./api.html#aggregate_Aggregate-cursor),
  751. * [`collation()`](./api.html#aggregate_Aggregate-collation), etc. helpers to
  752. * set individual options, or access `agg.options` directly.
  753. *
  754. * Note that MongoDB aggregations [do **not** support the `noCursorTimeout` flag](https://jira.mongodb.org/browse/SERVER-6036),
  755. * if you try setting that flag with this function you will get a "unrecognized field 'noCursorTimeout'" error.
  756. *
  757. * @param {String} flag
  758. * @param {Boolean} value
  759. * @return {Aggregate} this
  760. * @api public
  761. * @deprecated Use [`.option()`](api.html#aggregate_Aggregate-option) instead. Note that MongoDB aggregations do **not** support a `noCursorTimeout` option.
  762. */
  763. Aggregate.prototype.addCursorFlag = util.deprecate(function(flag, value) {
  764. if (!this.options) {
  765. this.options = {};
  766. }
  767. this.options[flag] = value;
  768. return this;
  769. }, 'Mongoose: `Aggregate#addCursorFlag()` is deprecated, use `option()` instead');
  770. /**
  771. * Adds a collation
  772. *
  773. * ####Example:
  774. *
  775. * Model.aggregate(..).collation({ locale: 'en_US', strength: 1 }).exec();
  776. *
  777. * @param {Object} collation options
  778. * @return {Aggregate} this
  779. * @api public
  780. * @see mongodb http://mongodb.github.io/node-mongodb-native/2.2/api/Collection.html#aggregate
  781. */
  782. Aggregate.prototype.collation = function(collation) {
  783. if (!this.options) {
  784. this.options = {};
  785. }
  786. this.options.collation = collation;
  787. return this;
  788. };
  789. /**
  790. * Combines multiple aggregation pipelines.
  791. *
  792. * ####Example:
  793. *
  794. * Model.aggregate(...)
  795. * .facet({
  796. * books: [{ groupBy: '$author' }],
  797. * price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }]
  798. * })
  799. * .exec();
  800. *
  801. * // Output: { books: [...], price: [{...}, {...}] }
  802. *
  803. * @param {Object} facet options
  804. * @return {Aggregate} this
  805. * @see $facet https://docs.mongodb.com/v3.4/reference/operator/aggregation/facet/
  806. * @api public
  807. */
  808. Aggregate.prototype.facet = function(options) {
  809. return this.append({$facet: options});
  810. };
  811. /**
  812. * Returns the current pipeline
  813. *
  814. * ####Example:
  815. *
  816. * MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]
  817. *
  818. * @return {Array}
  819. * @api public
  820. */
  821. Aggregate.prototype.pipeline = function() {
  822. return this._pipeline;
  823. };
  824. /**
  825. * Executes the aggregate pipeline on the currently bound Model.
  826. *
  827. * ####Example:
  828. *
  829. * aggregate.exec(callback);
  830. *
  831. * // Because a promise is returned, the `callback` is optional.
  832. * var promise = aggregate.exec();
  833. * promise.then(..);
  834. *
  835. * @see Promise #promise_Promise
  836. * @param {Function} [callback]
  837. * @return {Promise}
  838. * @api public
  839. */
  840. Aggregate.prototype.exec = function(callback) {
  841. if (!this._model) {
  842. throw new Error('Aggregate not bound to any Model');
  843. }
  844. const model = this._model;
  845. const pipeline = this._pipeline;
  846. const collection = this._model.collection;
  847. if (this.options && this.options.cursor) {
  848. return new AggregationCursor(this);
  849. }
  850. return utils.promiseOrCallback(callback, cb => {
  851. if (!pipeline.length) {
  852. const err = new Error('Aggregate has empty pipeline');
  853. return cb(err);
  854. }
  855. prepareDiscriminatorPipeline(this);
  856. model.hooks.execPre('aggregate', this, error => {
  857. if (error) {
  858. const _opts = { error: error };
  859. return model.hooks.execPost('aggregate', this, [null], _opts, error => {
  860. cb(error);
  861. });
  862. }
  863. const options = utils.clone(this.options || {});
  864. collection.aggregate(pipeline, options, (error, cursor) => {
  865. if (error) {
  866. const _opts = { error: error };
  867. return model.hooks.execPost('aggregate', this, [null], _opts, error => {
  868. if (error) {
  869. return cb(error);
  870. }
  871. return cb(null);
  872. });
  873. }
  874. cursor.toArray((error, result) => {
  875. const _opts = { error: error };
  876. model.hooks.execPost('aggregate', this, [result], _opts, (error, result) => {
  877. if (error) {
  878. return cb(error);
  879. }
  880. cb(null, result);
  881. });
  882. });
  883. });
  884. });
  885. }, model.events);
  886. };
  887. /**
  888. * Provides promise for aggregate.
  889. *
  890. * ####Example:
  891. *
  892. * Model.aggregate(..).then(successCallback, errorCallback);
  893. *
  894. * @see Promise #promise_Promise
  895. * @param {Function} [resolve] successCallback
  896. * @param {Function} [reject] errorCallback
  897. * @return {Promise}
  898. */
  899. Aggregate.prototype.then = function(resolve, reject) {
  900. return this.exec().then(resolve, reject);
  901. };
  902. /**
  903. * Executes the query returning a `Promise` which will be
  904. * resolved with either the doc(s) or rejected with the error.
  905. * Like [`.then()`](#query_Query-then), but only takes a rejection handler.
  906. *
  907. * @param {Function} [reject]
  908. * @return {Promise}
  909. * @api public
  910. */
  911. Aggregate.prototype.catch = function(reject) {
  912. return this.exec().then(null, reject);
  913. };
  914. /**
  915. * Returns an asyncIterator for use with [`for/await/of` loops](http://bit.ly/async-iterators)
  916. * This function *only* works for `find()` queries.
  917. * You do not need to call this function explicitly, the JavaScript runtime
  918. * will call it for you.
  919. *
  920. * ####Example
  921. *
  922. * for await (const doc of Model.find().sort({ name: 1 })) {
  923. * console.log(doc.name);
  924. * }
  925. *
  926. * Node.js 10.x supports async iterators natively without any flags. You can
  927. * 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).
  928. *
  929. * **Note:** This function is not if `Symbol.asyncIterator` is undefined. If
  930. * `Symbol.asyncIterator` is undefined, that means your Node.js version does not
  931. * support async iterators.
  932. *
  933. * @method Symbol.asyncIterator
  934. * @memberOf Aggregate
  935. * @instance
  936. * @api public
  937. */
  938. if (Symbol.asyncIterator != null) {
  939. Aggregate.prototype[Symbol.asyncIterator] = function() {
  940. return this.cursor({ useMongooseAggCursor: true }).
  941. exec().
  942. transformNull().
  943. map(doc => {
  944. return doc == null ? { done: true } : { value: doc, done: false };
  945. });
  946. };
  947. }
  948. /*!
  949. * Helpers
  950. */
  951. /**
  952. * Checks whether an object is likely a pipeline operator
  953. *
  954. * @param {Object} obj object to check
  955. * @return {Boolean}
  956. * @api private
  957. */
  958. function isOperator(obj) {
  959. if (typeof obj !== 'object') {
  960. return false;
  961. }
  962. const k = Object.keys(obj);
  963. return k.length === 1 && k.some(key => { return key[0] === '$'; });
  964. }
  965. /*!
  966. * Adds the appropriate `$match` pipeline step to the top of an aggregate's
  967. * pipeline, should it's model is a non-root discriminator type. This is
  968. * analogous to the `prepareDiscriminatorCriteria` function in `lib/query.js`.
  969. *
  970. * @param {Aggregate} aggregate Aggregate to prepare
  971. */
  972. Aggregate._prepareDiscriminatorPipeline = prepareDiscriminatorPipeline;
  973. function prepareDiscriminatorPipeline(aggregate) {
  974. const schema = aggregate._model.schema;
  975. const discriminatorMapping = schema && schema.discriminatorMapping;
  976. if (discriminatorMapping && !discriminatorMapping.isRoot) {
  977. const originalPipeline = aggregate._pipeline;
  978. const discriminatorKey = discriminatorMapping.key;
  979. const discriminatorValue = discriminatorMapping.value;
  980. // If the first pipeline stage is a match and it doesn't specify a `__t`
  981. // key, add the discriminator key to it. This allows for potential
  982. // aggregation query optimizations not to be disturbed by this feature.
  983. if (originalPipeline[0] && originalPipeline[0].$match && !originalPipeline[0].$match[discriminatorKey]) {
  984. originalPipeline[0].$match[discriminatorKey] = discriminatorValue;
  985. // `originalPipeline` is a ref, so there's no need for
  986. // aggregate._pipeline = originalPipeline
  987. } else if (originalPipeline[0] && originalPipeline[0].$geoNear) {
  988. originalPipeline[0].$geoNear.query =
  989. originalPipeline[0].$geoNear.query || {};
  990. originalPipeline[0].$geoNear.query[discriminatorKey] = discriminatorValue;
  991. } else {
  992. const match = {};
  993. match[discriminatorKey] = discriminatorValue;
  994. aggregate._pipeline.unshift({ $match: match });
  995. }
  996. }
  997. }
  998. /*!
  999. * Exports
  1000. */
  1001. module.exports = Aggregate;