聚合

用於建構聚合管道的聚合建構函式。請勿直接實例化此類別，請改用 Model.aggregate()。

範例

const aggregate = Model.aggregate([
  { $project: { a: 1, b: 1 } },
  { $skip: 5 }
]);

Model.
  aggregate([{ $match: { age: { $gte: 21 }}}]).
  unwind('tags').
  exec();

注意

• 傳回的文件是純 JavaScript 物件，而不是 Mongoose 文件（因為可以傳回任何形狀的文件）。

• Mongoose 不會轉換管道階段。除非 _id 在資料庫中是字串，否則以下程式碼不會運作

  new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]); // 請改為執行此操作以轉換為 ObjectId new Aggregate([{ $match: { _id: new mongoose.Types.ObjectId('00000000000000000000000a') } }]);

將新的 $addFields 運算子附加到此聚合管道。需要 MongoDB v3.4+ 才能運作

範例

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

設定聚合查詢的 allowDiskUse 選項

範例

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

將新的運算子附加到此聚合管道

範例

aggregate.append({ $project: { field: 1 }}, { $limit: 2 });

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

執行聚合，傳回一個 Promise，該 Promise 將會使用 doc(s) 來解析，或使用錯誤來拒絕。類似 .then()，但僅接受拒絕處理常式。與 await 相容。

新增排序規則

範例

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

將新的 $count 運算子附加到此聚合管道。

範例

aggregate.count("userCount");

設定 cursor 選項並執行此聚合，傳回聚合游標。如果您想要一次處理一個聚合結果，因為聚合結果太大而無法放入記憶體，則游標非常有用。

範例

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

將新的 $densify 運算子附加到此聚合管道。

範例

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

在目前繫結的 Model 上執行聚合管道。

範例

const result = await aggregate.exec();

使用 explain 執行聚合

範例

Model.aggregate(..).explain()

合併多個聚合管道。

範例

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

// Output: { books: [...], price: [{...}, {...}] }

將新的 $fill 運算子附加到此聚合管道。

範例

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

執行聚合，傳回一個 Promise，該 Promise 將會與 .finally() 鏈結解析。

有關 JavaScript 中的 Promise finally() 的詳細資訊。

將新的自訂 $graphLookup 運算子附加到此聚合管道，對集合執行遞迴搜尋。

請注意，graphLookup 最多只能消耗 100MB 的記憶體，即使指定了 { allowDiskUse: true }，也不允許使用磁碟。

範例

 // 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

將新的自訂 $group 運算子附加到此聚合管道。

範例

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

設定聚合查詢的 hint 選項

範例

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

將新的 $limit 運算子附加到此聚合管道。

範例

aggregate.limit(10);

將新的自訂 $lookup 運算子附加到此聚合管道。

範例

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

將新的自訂 $match 運算子附加到此聚合管道。

範例

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

取得/設定此聚合將執行的模型。

範例

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

將新的 $geoNear 運算子附加到此聚合管道。

注意

必須用作管道中的第一個運算子。

範例

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

讓您可以設定任意選項，以用於中介軟體或外掛程式。

範例

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

包含傳遞至 aggregate 命令的選項。支援的選項有

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

傳回目前的管道

範例

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

將新的 $project 運算子附加到此聚合管道。

也支援 Mongoose 查詢 選擇語法。

範例

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

設定聚合查詢的 readPreference 選項。

範例

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

設定聚合查詢的讀取關注層級。

範例

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

將新的 $redact 運算子附加到此聚合管道。

如果提供 3 個引數，則 Mongoose 會分別使用 $cond 運算子的 if-then-else 包裝它們。如果 thenExpr 或 elseExpr 是字串，請確保它以 $$ 開頭，例如 $$DESCEND、$$PRUNE 或 $$KEEP。

範例

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

將新的 $replaceRoot 運算子附加到此聚合管道。

請注意，$replaceRoot 運算子要求欄位字串以 '$' 開頭。如果您傳遞的是字串，則如果指定的欄位未以 '$' 開頭，Mongoose 將會預先加上 '$'。如果您傳遞的是物件，則您運算式中的字串將不會被變更。

範例

aggregate.replaceRoot("user");

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

將新的自訂 $sample 運算子附加到此聚合管道。

範例

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

用於 Atlas 文字搜尋 的 $search 階段的 Helper。

範例

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

// Output: [{ plot: '...', title: '...' }]

設定此聚合的階段。對於 交易 非常有用。

範例

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

將新的 $skip 運算子附加到此聚合管道。

範例

aggregate.skip(10);

將新的 $sort 運算子附加到此聚合管道。

如果傳入的是物件，則允許的值為 asc、desc、ascending、descending、1 和 -1。

如果傳入的是字串，則它必須是以空格分隔的路徑名稱清單。每個路徑的排序順序都是遞增的，除非路徑名稱以 - 作為前綴，否則會被視為遞減。

範例

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

將新的 $sortByCount 運算子附加到此聚合管道。接受字串欄位名稱或管道物件。

請注意，$sortByCount 運算子要求新的根以 '$' 開頭。如果指定的欄位名稱不是以 '$' 開頭，Mongoose 將會加上 '$' 前綴。

範例

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

提供一個類似 Promise 的 then 函式，它將在沒有回呼的情況下呼叫 .exec。與 await 相容。

範例

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

將新的 $unionWith 運算子附加到此聚合管道。

範例

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

將新的自訂 $unwind 運算子附加到此聚合管道。

請注意，$unwind 運算子要求路徑名稱以 '$' 開頭。如果指定的欄位不是以 '$' 開頭，Mongoose 將會加上 '$' 前綴。

範例

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

傳回一個 asyncIterator，用於 for/await/of 迴圈。您不需要明確呼叫此函式，JavaScript 執行時環境會為您呼叫它。

範例

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

Node.js 10.x 原生支援 async iterators，無需任何標誌。您可以使用 --harmony_async_iteration 標誌在 Node.js 8.x 中啟用 async iterators。

注意： 如果 Symbol.asyncIterator 未定義，則不會設定此函式。如果 Symbol.asyncIterator 未定義，表示您的 Node.js 版本不支援 async iterators。