查詢（Query）

用於建立查詢的 Query 建構函式。您不需要直接實例化 Query。而是使用模型函數，例如 Model.find()。

範例

const query = MyModel.find(); // `query` is an instance of `Query`
query.setOptions({ lean : true });
query.collection(MyModel.collection);
query.where('age').gte(21).exec(callback);

// You can instantiate a query directly. There is no need to do
// this unless you're an advanced user with a very good reason to.
const query = new mongoose.Query();

指定要傳遞給 MongoDB 查詢系統的 javascript 函數或表達式。

範例

query.$where('this.comments.length === 10 || this.name.length === 5')

// or

query.$where(function () {
  return this.comments.length === 10 || this.name.length === 5;
})

注意

只有在您有無法使用其他 MongoDB 運算符（例如 $lt）滿足的條件時才使用 $where。在使用之前，請務必閱讀關於其所有注意事項。

指定 $all 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

範例

MyModel.find().where('pets').all(['dog', 'cat', 'ferret']);
// Equivalent:
MyModel.find().all('pets', ['dog', 'cat', 'ferret']);

設定 allowDiskUse 選項，該選項允許 MongoDB 伺服器對此查詢的 sort() 使用超過 100 MB 的記憶體。此選項可讓您解決來自 MongoDB 伺服器的 QueryExceededMemoryLimitNoDiskUseAllowed 錯誤。

請注意，此選項需要 MongoDB 伺服器 >= 4.4。對於 MongoDB 4.2 和更早版本，設定此選項無效。

呼叫 query.allowDiskUse(v) 等效於 query.setOptions({ allowDiskUse: v })

範例

await query.find().sort({ name: 1 }).allowDiskUse(true);
// Equivalent:
await query.find().sort({ name: 1 }).allowDiskUse();

指定 $and 條件的參數。

範例

query.and([{ color: 'green' }, { status: 'ok' }])

指定 batchSize 選項。

範例

query.batchSize(100)

注意

不能與 distinct() 一起使用

指定 $box 條件

範例

const lowerLeft = [40.73083, -73.99756]
const upperRight= [40.741404,  -73.988135]

query.where('loc').within().box(lowerLeft, upperRight)
query.box({ ll : lowerLeft, ur : upperRight })

將此查詢轉換為 model 的綱要

注意

如果存在 obj，則會轉換它而不是此查詢。

執行查詢，傳回 Promise，該 Promise 將使用 doc(s) 解析或使用錯誤拒絕。類似於 .then()，但僅採用拒絕處理常式。

更多關於 JavaScript 中的 Promise catch()。

已棄用 circle 的別名

已棄用。 請改用 circle。

已棄用 指定 $centerSphere 條件

已棄用。 請改用 circle。

範例

const area = { center: [50, 50], radius: 10 };
query.where('loc').within().centerSphere(area);

指定 $center 或 $centerSphere 條件。

範例

const area = { center: [50, 50], radius: 10, unique: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

// spherical calculations
const area = { center: [50, 50], radius: 10, unique: true, spherical: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

建立此查詢的複本，以便您可以重新執行它。

範例

const q = Book.findOne({ title: 'Casino Royale' });
await q.exec();
await q.exec(); // Throws an error because you can't execute a query twice

await q.clone().exec(); // Works

將排序規則新增至此操作 (MongoDB 3.4 及更新版本)

指定 comment 選項。

範例

query.comment('login query')

注意

不能與 distinct() 一起使用

將此查詢指定為 countDocuments() 查詢。行為類似於 count()，但當傳遞空篩選器 {} 時，它始終執行完整的集合掃描。

在 countDocuments() 如何處理 $where 和幾個地理空間運算符 與 count() 之間也存在一些細微差異。

此函數會觸發以下中間件。

• countDocuments()

範例

const countQuery = model.where({ 'color': 'black' }).countDocuments();

query.countDocuments({ color: 'black' }).count().exec();

await query.countDocuments({ color: 'black' });

query.where('color', 'black').countDocuments().exec();

countDocuments() 函數類似於 count()，但 countDocuments() 不支援一些運算符。以下是 count() 支援但 countDocuments() 不支援的運算符，以及建議的替代方案

• $where：$expr
• $near：$geoWithin 與 $center
• $nearSphere：$geoWithin 與 $centerSphere

傳回 mongodb 驅動程式游標 的包裝函式。QueryCursor 會公開 Streams3 介面，以及 .next() 函數。

.cursor() 函數會觸發 pre find 鉤子，但不會觸發 post find 鉤子。

範例

// There are 2 ways to use a cursor. First, as a stream:
Thing.
  find({ name: /^hello/ }).
  cursor().
  on('data', function(doc) { console.log(doc); }).
  on('end', function() { console.log('Done!'); });

// Or you can use `.next()` to manually get the next doc in the stream.
// `.next()` returns a promise, so you can use promises or callbacks.
const cursor = Thing.find({ name: /^hello/ }).cursor();
cursor.next(function(error, doc) {
  console.log(doc);
});

// Because `.next()` returns a promise, you can use co
// to easily iterate through all documents without loading them
// all into memory.
const cursor = Thing.find({ name: /^hello/ }).cursor();
for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
  console.log(doc);
}

有效的選項

• transform：可選函數，接受 mongoose 文件。該函數的傳回值將在 data 上發出，並由 .next() 傳回。

將此查詢宣告和/或執行為 deleteMany() 操作。運作方式類似於 remove，但它會刪除集合中符合 filter 的每個文件，而不管 single 的值為何。

此函數會觸發 deleteMany 中間件。

範例

await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });

此函數會呼叫 MongoDB 驅動程式的 Collection#deleteMany() 函數。傳回的 promise 會解析為包含 3 個屬性的物件

• ok：如果沒有發生錯誤，則為 1
• deletedCount：已刪除的文件數
• n：已刪除的文件數。等於 deletedCount。

範例

const res = await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } });
// `0` if no docs matched the filter, number of docs deleted otherwise
res.deletedCount;

將此查詢宣告和/或執行為 deleteOne() 操作。運作方式類似於 remove，但它最多會刪除一個文件，而不管 single 選項為何。

此函數會觸發 deleteOne 中間件。

範例

await Character.deleteOne({ name: 'Eddard Stark' });

此函數會呼叫 MongoDB 驅動程式的 Collection#deleteOne() 函數。傳回的 promise 會解析為包含 3 個屬性的物件

• ok：如果沒有發生錯誤，則為 1
• deletedCount：已刪除的文件數
• n：已刪除的文件數。等於 deletedCount。

範例

const res = await Character.deleteOne({ name: 'Eddard Stark' });
// `1` if MongoDB deleted a doc, `0` if no docs matched the filter `{ name: ... }`
res.deletedCount;

宣告或執行 distinct() 操作。

此函數不會觸發任何中間件。

範例

distinct(field, conditions, options)
distinct(field, conditions)
distinct(field)
distinct()

指定 $elemMatch 條件

範例

query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})

query.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}})

query.elemMatch('comment', function (elem) {
  elem.where('author').equals('autobot');
  elem.where('votes').gte(5);
})

query.where('comment').elemMatch(function (elem) {
  elem.where({ author: 'autobot' });
  elem.where('votes').gte(5);
})

為使用 where() 指定的路徑指定補充比較值

範例

User.where('age').equals(49);

// is the same as

User.where('age', 49);

取得/設定此查詢的錯誤旗標。如果此旗標不是 null 或未定義，則 exec() promise 將在不執行的情況下拒絕。

範例

Query().error(); // Get current error value
Query().error(null); // Unset the current error
Query().error(new Error('test')); // `exec()` will resolve with test
Schema.pre('find', function() {
  if (!this.getQuery().userId) {
    this.error(new Error('Not allowed to query without setting userId'));
  }
});

請注意，查詢轉換會在鉤子之後執行，因此轉換錯誤將覆寫自訂錯誤。

範例

const TestSchema = new Schema({ num: Number });
const TestModel = db.model('Test', TestSchema);
TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
  // `error` will be a cast error because `num` failed to cast
});

將此查詢指定為 estimatedDocumentCount() 查詢。對於大型集合而言，比使用 countDocuments() 更快，因為 estimatedDocumentCount() 使用集合元數據而不是掃描整個集合。

estimatedDocumentCount()不接受篩選器。Model.find({ foo: bar }).estimatedDocumentCount() 等效於 Model.find().estimatedDocumentCount()

此函數會觸發以下中間件。

• estimatedDocumentCount()

範例

await Model.find().estimatedDocumentCount();

執行查詢。

範例

const promise = query.exec();
const promise = query.exec('update');

指定一個 $exists 條件。

範例

// { name: { $exists: true }}
Thing.where('name').exists()
Thing.where('name').exists(true)
Thing.find().exists('name')

// { name: { $exists: false }}
Thing.where('name').exists(false);
Thing.find().exists('name', false);

設定 explain 選項，這會使此查詢返回詳細的執行統計資訊，而不是實際的查詢結果。此方法對於確定您的查詢使用哪個索引很有用。

呼叫 query.explain(v) 等同於 query.setOptions({ explain: v })。

範例

const query = new Query();
const res = await query.find({ a: 1 }).explain('queryPlanner');
console.log(res);

執行查詢，返回一個 Promise，該 Promise 將以鏈接的 .finally() 解析。

更多關於 JavaScript 中的 Promise finally()。

尋找所有符合 selector 的文件。結果將是文件的陣列。

如果結果中有太多文件無法放入記憶體，請使用 Query.prototype.cursor()。

範例

const arr = await Movie.find({ year: { $gte: 1980, $lte: 1989 } });

宣告此查詢為 findOne 操作。執行時，找到的第一個文件將傳遞給回呼函數。

查詢的結果是單個文件，如果沒有找到任何文件，則為 null。

• 注意： conditions 是可選的，如果 conditions 為 null 或 undefined，mongoose 將向 MongoDB 發送一個空的 findOne 命令，這將返回一個任意的文件。如果您要按 _id 查詢，請改用 Model.findById()。

此函數會觸發以下中間件。

• findOne()

範例

const query = Kitten.where({ color: 'white' });
const kitten = await query.findOne();

發出 MongoDB findOneAndDelete 命令。

尋找符合條件的文件，將其刪除，並返回找到的文件（如果有）。

此函數會觸發以下中間件。

• findOneAndDelete()

可用的選項

• sort：如果條件找到多個文件，則設定排序順序以選擇要更新的文件。
• maxTimeMS：設定查詢的時間限制 - 需要 mongodb >= 2.6.0。

回呼簽名

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

範例

A.where().findOneAndDelete(conditions, options)  // return Query
A.where().findOneAndDelete(conditions) // returns Query
A.where().findOneAndDelete()           // returns Query

發出 MongoDB findOneAndReplace 命令。

尋找符合條件的文件，將其刪除，並返回找到的文件（如果有）。

此函數會觸發以下中間件。

• findOneAndReplace()

可用的選項

• sort：如果條件找到多個文件，則設定排序順序以選擇要更新的文件。
• maxTimeMS：設定查詢的時間限制 - 需要 mongodb >= 2.6.0。
• includeResultMetadata：如果為 true，則返回完整的 來自 MongoDB 驅動程式的 ModifyResult，而不僅僅是文件。

回呼簽名

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

範例

A.where().findOneAndReplace(filter, replacement, options); // return Query
A.where().findOneAndReplace(filter); // returns Query
A.where().findOneAndReplace(); // returns Query

發出 mongodb findOneAndUpdate() 命令。

尋找符合條件的文件，根據 update 參數更新它，傳遞任何 options，並返回找到的文件（如果有）。

此函數會觸發以下中間件。

• findOneAndUpdate()

可用的選項

• new：bool - 如果為 true，則返回修改後的文件，而不是原始文件。預設值為 false (在 4.0 中變更)。
• upsert：bool - 如果物件不存在則建立該物件。預設值為 false。
• fields：{Object|String} - 欄位選擇。等同於 .select(fields).findOneAndUpdate()。
• sort：如果條件找到多個文件，則設定排序順序以選擇要更新的文件。
• maxTimeMS：設定查詢的時間限制 - 需要 mongodb >= 2.6.0。
• runValidators：如果為 true，則在此命令上執行更新驗證器。更新驗證器根據模型的 schema 驗證更新操作。
• setDefaultsOnInsert：預設值為 true。如果 setDefaultsOnInsert 和 upsert 為 true，如果建立新文件，mongoose 將應用模型 schema 中指定的預設值。

範例

query.findOneAndUpdate(conditions, update, options)  // returns Query
query.findOneAndUpdate(conditions, update)           // returns Query
query.findOneAndUpdate(update)                       // returns Query
query.findOneAndUpdate()                             // returns Query

指定 $geometry 條件。

範例

const polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })

// or
const polyB = [[ 0, 0 ], [ 1, 1 ]]
query.where('loc').within().geometry({ type: 'LineString', coordinates: polyB })

// or
const polyC = [ 0, 0 ]
query.where('loc').within().geometry({ type: 'Point', coordinates: polyC })

// or
query.where('loc').intersects().geometry({ type: 'Point', coordinates: polyC })

該參數會分配給最近傳遞給 where() 的路徑。

注意

geometry() 必須 在 intersects() 或 within() 之後使用。

object 參數必須包含 type 和 coordinates 屬性。

• type {String}
• coordinates {Array}

對於更新操作，返回更新的 $set 中路徑的值。對於編寫可以用於更新操作和 save() 的 getter/setter 很有用。

範例

const query = Model.updateOne({}, { $set: { name: 'Jean-Luc Picard' } });
query.get('name'); // 'Jean-Luc Picard'

以 POJO 形式返回目前的查詢篩選器 (也稱為條件)。

範例

const query = new Query();
query.find({ a: 1 }).where('b').gt(2);
query.getFilter(); // { a: 1, b: { $gt: 2 } }

取得查詢選項。

範例

const query = new Query();
query.limit(10);
query.setOptions({ maxTimeMS: 1000 });
query.getOptions(); // { limit: 10, maxTimeMS: 1000 }

取得此查詢要填充的路徑清單。

範例

 bookSchema.pre('findOne', function() {
   let keys = this.getPopulatedPaths(); // ['author']
 });
 ...
 Book.findOne({}).populate('author');

範例

 // Deep populate
 const q = L1.find().populate({
   path: 'level2',
   populate: { path: 'level3' }
 });
 q.getPopulatedPaths(); // ['level2', 'level2.level3']

返回目前的查詢篩選器。等同於 getFilter()。

您應該盡可能使用 getFilter() 而不是 getQuery()。getQuery() 可能會在未來的版本中被棄用。

範例

const query = new Query();
query.find({ a: 1 }).where('b').gt(2);
query.getQuery(); // { a: 1, b: { $gt: 2 } }

以 JSON 物件形式返回目前的更新操作。

範例

const query = new Query();
query.updateOne({}, { $set: { a: 5 } });
query.getUpdate(); // { $set: { a: 5 } }

指定一個 $gt 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

範例

Thing.find().where('age').gt(21);

// or
Thing.find().gt('age', 21);

指定一個 $gte 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

設定查詢提示。

範例

query.hint({ indexA: 1, indexB: -1 });

注意

不能與 distinct() 一起使用

指定一個 $in 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

宣告 geometry() 的相交查詢。

範例

query.where('path').intersects().geometry({
  type: 'LineString',
  coordinates: [[180.0, 11.0], [180, 9.0]]
});

query.where('path').intersects({
  type: 'LineString',
  coordinates: [[180.0, 11.0], [180, 9.0]]
});

注意

必須 在 where() 之後使用。

注意

在 Mongoose 3.7 中，intersects 從 getter 更改為函數。如果您需要舊的語法，請使用這個。

呼叫查詢中 isPathSelectedInclusive 的包裝函式。

請求確認此操作已持久儲存到 MongoDB 的磁碟上日誌。此選項僅對寫入資料庫的操作有效。

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

預設為 schema 的 writeConcern.j 選項。

範例

await mongoose.model('Person').deleteOne({ name: 'Ned Stark' }).j(true);

設定 lean 選項。

從啟用 lean 選項的查詢返回的文件是純 javascript 物件，而不是Mongoose 文件。它們沒有 save 方法、getter/setter、虛擬屬性或其他 Mongoose 功能。

範例

new Query().lean() // true
new Query().lean(true)
new Query().lean(false)

const docs = await Model.find().lean();
docs[0] instanceof mongoose.Document; // false

Lean 非常適合高效能的唯讀情況，尤其是在與游標結合使用時。

如果您需要 lean() 的虛擬屬性、getter/setter 或預設值，則需要使用外掛程式。請參閱

• mongoose-lean-virtuals
• mongoose-lean-getters
• mongoose-lean-defaults

指定查詢將返回的最大文件數量。

範例

query.limit(20);

注意

不能與 distinct() 一起使用

指定一個 $lt 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

指定一個 $lte 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

指定一個 maxDistance 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

設定 maxTimeMS 選項。這將告知 MongoDB 伺服器，如果查詢或寫入操作執行時間超過 ms 毫秒，則中止。

呼叫 query.maxTimeMS(v) 等同於 query.setOptions({ maxTimeMS: v })。

範例

const query = new Query();
// Throws an error 'operation exceeded time limit' as long as there's
// >= 1 doc in the queried collection
const res = await query.find({ $where: 'sleep(1000) || true' }).maxTimeMS(100);

將另一個查詢或條件物件合併到此查詢中。

當傳遞查詢時，會合併條件、欄位選擇和選項。

指定一個 $mod 條件，篩選 path 屬性是一個數字且等於 divisor 除以 remainder 的文件。

範例

// All find products whose inventory is odd
Product.find().mod('inventory', [2, 1]);
Product.find().where('inventory').mod([2, 1]);
// This syntax is a little strange, but supported.
Product.find().where('inventory').mod(2, 1);

此查詢所關聯的模型。

範例

const q = MyModel.find();
q.model === MyModel; // true

此查詢的目前 mongoose 特定選項的 getter/setter。以下是目前的 Mongoose 特定選項。

• populate：代表將要填充的路徑的陣列。每次呼叫 Query.prototype.populate() 應有一個項目。
• lean：如果為真值，Mongoose 將不會 水合化 從此查詢返回的任何文件。請參閱 Query.prototype.lean() 以取得更多資訊。
• strict：控制 Mongoose 如何處理更新中不在 schema 中的鍵。此選項預設為 true，這表示 Mongoose 將會靜默地移除更新中不在 schema 中的任何路徑。請參閱strict 模式文件以取得更多資訊。
• strictQuery：控制 Mongoose 如何處理查詢 filter 中不屬於 schema 的鍵。此選項預設為 false，這表示即使 foo 不在 schema 中，Mongoose 也會允許 Model.find({ foo: 'bar' })。請參閱strictQuery 文件以獲取更多資訊。
• nearSphere：使用 $nearSphere 而非 near()。請參閱Query.prototype.nearSphere() 文件

Mongoose 為內部選項維護一個獨立的物件，因為 Mongoose 會將 Query.prototype.options 發送到 MongoDB 伺服器，而上述選項與 MongoDB 伺服器無關。

指定 $ne 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

指定 $near 或 $nearSphere 條件

這些運算子會傳回依距離排序的文件。

範例

query.where('loc').near({ center: [10, 10] });
query.where('loc').near({ center: [10, 10], maxDistance: 5 });
query.where('loc').near({ center: [10, 10], maxDistance: 5, spherical: true });
query.near('loc', { center: [10, 10], maxDistance: 5 });

已棄用 指定 $nearSphere 條件

範例

query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });

已棄用。 請改用 query.near() 並將 spherical 選項設定為 true。

範例

query.where('loc').near({ center: [10, 10], spherical: true });

指定 $nin 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

為 $nor 條件指定引數。

範例

query.nor([{ color: 'green' }, { status: 'ok' }]);

為 $or 條件指定引數。

範例

query.or([{ color: 'red' }, { status: 'emergency' }]);

如果沒有文件符合給定的 filter，則使此查詢拋出錯誤。這對於與 async/await 整合非常方便，因為 orFail() 可以節省您額外的 if 語句來檢查是否沒有找到文件。

範例

// Throws if no doc returned
await Model.findOne({ foo: 'bar' }).orFail();

// Throws if no document was updated. Note that `orFail()` will still
// throw if the only document that matches is `{ foo: 'bar', name: 'test' }`,
// because `orFail()` will throw if no document was _updated_, not
// if no document was _found_.
await Model.updateOne({ foo: 'bar' }, { name: 'test' }).orFail();

// Throws "No docs found!" error if no docs match `{ foo: 'bar' }`
await Model.find({ foo: 'bar' }).orFail(new Error('No docs found!'));

// Throws "Not found" error if no document was found
await Model.findOneAndUpdate({ foo: 'bar' }, { name: 'test' }).
  orFail(() => Error('Not found'));

指定 $polygon 條件

範例

query.where('loc').within().polygon([10, 20], [13, 25], [7, 15]);
query.polygon('loc', [10, 20], [13, 25], [7, 15]);

指定應該使用其他文件填充的路徑。

範例

let book = await Book.findOne().populate('authors');
book.title; // 'Node.js in Action'
book.authors[0].name; // 'TJ Holowaychuk'
book.authors[1].name; // 'Nathan Rajlich'

let books = await Book.find().populate({
  path: 'authors',
  // `match` and `sort` apply to the Author model,
  // not the Book model. These options do not affect
  // which documents are in `books`, just the order and
  // contents of each book document's `authors`.
  match: { name: new RegExp('.*h.*', 'i') },
  sort: { name: -1 }
});
books[0].title; // 'Node.js in Action'
// Each book's `authors` are sorted by name, descending.
books[0].authors[0].name; // 'TJ Holowaychuk'
books[0].authors[1].name; // 'Marc Harter'

books[1].title; // 'Professional AngularJS'
// Empty array, no authors' name has the letter 'h'
books[1].authors; // []

路徑會在查詢執行並收到回應後填充。然後會針對指定的每個填充路徑執行個別的查詢。在也傳回每個查詢的回應後，結果會傳遞給回呼。

將後置中介軟體新增到此查詢實例。不會影響其他查詢。

範例

const q1 = Question.find({ answer: 42 });
q1.post(function middleware() {
  console.log(this.getFilter());
});
await q1.exec(); // Prints "{ answer: 42 }"

// Doesn't print anything, because `middleware()` is only
// registered on `q1`.
await Question.find({ answer: 42 });

將前置中介軟體新增到此查詢實例。不會影響其他查詢。

範例

const q1 = Question.find({ answer: 42 });
q1.pre(function middleware() {
  console.log(this.getFilter());
});
await q1.exec(); // Prints "{ answer: 42 }"

// Doesn't print anything, because `middleware()` is only
// registered on `q1`.
await Question.find({ answer: 42 });

取得/設定目前的投影 (也稱為欄位)。傳遞 null 以移除目前的投影。

與 projection() 不同，select() 函式會就地修改目前的投影。此函式會覆寫現有的投影。

範例

const q = Model.find();
q.projection(); // null

q.select('a b');
q.projection(); // { a: 1, b: 1 }

q.projection({ c: 1 });
q.projection(); // { c: 1 }

q.projection(null);
q.projection(); // null

決定從哪個 MongoDB 節點讀取。

偏好設定

primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
secondary            Read from secondary if available, otherwise error.
primaryPreferred     Read from primary if available, otherwise a secondary.
secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.

別名

p   primary
pp  primaryPreferred
s   secondary
sp  secondaryPreferred
n   nearest

範例

new Query().read('primary')
new Query().read('p')  // same as primary

new Query().read('primaryPreferred')
new Query().read('pp') // same as primaryPreferred

new Query().read('secondary')
new Query().read('s')  // same as secondary

new Query().read('secondaryPreferred')
new Query().read('sp') // same as secondaryPreferred

new Query().read('nearest')
new Query().read('n')  // same as nearest

// read from secondaries with matching tags
new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])

若要深入瞭解如何使用讀取偏好設定，請參閱此處。

設定查詢的 readConcern 選項。

範例

new Query().readConcern('local')
new Query().readConcern('l')  // same as local

new Query().readConcern('available')
new Query().readConcern('a')  // same as available

new Query().readConcern('majority')
new Query().readConcern('m')  // same as majority

new Query().readConcern('linearizable')
new Query().readConcern('lz') // same as linearizable

new Query().readConcern('snapshot')
new Query().readConcern('s')  // same as snapshot

讀取關注層級

local         MongoDB 3.2+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
available     MongoDB 3.6+ The query returns from the instance with no guarantee guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back).
majority      MongoDB 3.2+ The query returns the data that has been acknowledged by a majority of the replica set members. The documents returned by the read operation are durable, even in the event of failure.
linearizable  MongoDB 3.4+ The query returns data that reflects all successful majority-acknowledged writes that completed prior to the start of the read operation. The query may wait for concurrently executing writes to propagate to a majority of replica set members before returning results.
snapshot      MongoDB 4.0+ Only available for operations within multi-document transactions. Upon transaction commit with write concern "majority", the transaction operations are guaranteed to have read from a snapshot of majority-committed data.

別名

l   local
a   available
m   majority
lz  linearizable
s   snapshot

若要深入瞭解如何使用讀取關注，請參閱此處。

指定 $regex 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

宣告和/或將此查詢作為 replaceOne() 操作執行。MongoDB 將會取代現有的文件，並且不會接受任何原子運算子 ($set 等)

注意 replaceOne 將不會觸發更新中介軟體。請改用 pre('replaceOne') 和 post('replaceOne')。

範例

const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
res.acknowledged; // Indicates if this write result was acknowledged. If not, then all other members of this result will be undefined.
res.matchedCount; // Number of documents that matched the filter
res.modifiedCount; // Number of documents that were modified
res.upsertedCount; // Number of documents that were upserted
res.upsertedId; // Identifier of the inserted document (if an upsert took place)

此函數會觸發以下中間件。

• replaceOne()

設定此查詢的 sanitizeProjection 選項。如果設定，sanitizeProjection 會執行兩項操作

1. 強制投影值為數字，而不是字串。
2. 防止使用 + 語法來覆寫預設取消選取的屬性。

使用 sanitizeProjection()，您可以將可能不受信任的使用者資料傳遞給 .select()。

範例

const userSchema = new Schema({
  name: String,
  password: { type: String, select: false }
});
const UserModel = mongoose.model('User', userSchema);
const { _id } = await UserModel.create({ name: 'John', password: 'secret' })

// The MongoDB server has special handling for string values that start with '$'
// in projections, which can lead to unexpected leaking of sensitive data.
let doc = await UserModel.findOne().select({ name: '$password' });
doc.name; // 'secret'
doc.password; // undefined

// With `sanitizeProjection`, Mongoose forces all projection values to be numbers
doc = await UserModel.findOne().sanitizeProjection(true).select({ name: '$password' });
doc.name; // 'John'
doc.password; // undefined

// By default, Mongoose supports projecting in `password` using `+password`
doc = await UserModel.findOne().select('+password');
doc.password; // 'secret'

// With `sanitizeProjection`, Mongoose prevents projecting in `password` and other
// fields that have `select: false` in the schema.
doc = await UserModel.findOne().sanitizeProjection(true).select('+password');
doc.password; // undefined

指定要包含或排除的檔案欄位（也稱為查詢「投影」）

使用字串語法時，在路徑前面加上 - 將會將該路徑標示為排除。當路徑沒有 - 字首時，會包含該路徑。最後，如果路徑有 + 字首，則會強制包含該路徑，這對於在結構描述層級排除的路徑非常有用。

投影必須是包含或排除。換句話說，您必須列出要包含的欄位（這會排除所有其他欄位），或列出要排除的欄位（這表示包含所有其他欄位）。_id 欄位是唯一的例外，因為 MongoDB 預設會包含它。

範例

// include a and b, exclude other fields
query.select('a b');
// Equivalent syntaxes:
query.select(['a', 'b']);
query.select({ a: 1, b: 1 });

// exclude c and d, include other fields
query.select('-c -d');

// Use `+` to override schema-level `select: false` without making the
// projection inclusive.
const schema = new Schema({
  foo: { type: String, select: false },
  bar: String
});
// ...
query.select('+foo'); // Override foo's `select: false` without excluding `bar`

// or you may use object notation, useful when
// you have keys already prefixed with a "-"
query.select({ a: 1, b: 1 });
query.select({ c: 0, d: 0 });

Additional calls to select can override the previous selection:
query.select({ a: 1, b: 1 }).select({ b: 0 }); // selection is now { a: 1 }
query.select({ a: 0, b: 0 }).select({ b: 1 }); // selection is now { a: 0 }

判斷是否已進行欄位選取。

判斷是否已進行排除欄位選取。

query.selectedExclusively(); // false
query.select('-name');
query.selectedExclusively(); // true
query.selectedInclusively(); // false

判斷是否已進行包含欄位選取。

query.selectedInclusively(); // false
query.select('name');
query.selectedInclusively(); // true

設定與此查詢相關聯的MongoDB 工作階段。工作階段是您如何將查詢標記為交易的一部分。

呼叫 session(null) 會從此查詢中移除工作階段。

範例

const s = await mongoose.startSession();
await mongoose.model('Person').findOne({ name: 'Axl Rose' }).session(s);

將 $set 新增到此查詢的更新，而不變更操作。這對於查詢中介軟體非常有用，因此無論您使用 updateOne()、updateMany()、findOneAndUpdate() 等，都可以新增更新。

範例

// Updates `{ $set: { updatedAt: new Date() } }`
new Query().updateOne({}, {}).set('updatedAt', new Date());
new Query().updateMany({}, {}).set({ updatedAt: new Date() });

設定查詢選項。某些選項僅對特定操作有意義。

選項

以下選項僅適用於 find()

• tailable
• limit
• skip
• allowDiskUse
• batchSize
• readPreference
• hint
• comment

以下選項僅適用於寫入操作：updateOne()、updateMany()、replaceOne()、findOneAndUpdate() 和 findByIdAndUpdate()

• upsert
• writeConcern
• timestamps：如果在結構描述中設定了 timestamps，則將此選項設定為 false 以跳過該特定更新的時間戳記。如果結構描述選項中未啟用 timestamps，則無任何作用。
• overwriteDiscriminatorKey：允許在更新中設定區別鍵。如果更新變更了區別鍵，則將使用正確的區別結構描述。

以下選項僅適用於 find()、findOne()、findById()、findOneAndUpdate()、findOneAndReplace()、findOneAndDelete() 和 findByIdAndUpdate()

• lean
• populate
• projection
• sanitizeProjection
• useBigInt64

以下選項僅適用於除 updateOne()、updateMany()、deleteOne() 和 deleteMany() 之外的所有操作

• maxTimeMS

以下選項適用於 find()、findOne()、findOneAndUpdate()、findOneAndDelete()、updateOne() 和 deleteOne()

• sort

以下選項適用於 findOneAndUpdate() 和 findOneAndDelete()

• includeResultMetadata

以下選項適用於所有操作

• strict
• collation
• session
• explain

將查詢條件設定為提供的 JSON 物件。

範例

const query = new Query();
query.find({ a: 1 })
query.setQuery({ a: 2 });
query.getQuery(); // { a: 2 }

將目前的更新操作設定為新值。

範例

const query = new Query();
query.updateOne({}, { $set: { a: 5 } });
query.setUpdate({ $set: { b: 6 } });
query.getUpdate(); // { $set: { b: 6 } }

指定 $size 查詢條件。

當使用一個參數呼叫時，將使用傳遞給 where() 的最近路徑。

範例

const docs = await MyModel.where('tags').size(0).exec();
assert(Array.isArray(docs));
console.log('documents with 0 tags', docs);

指定要跳過的文件數。

範例

query.skip(100).limit(20);

注意

不能與 distinct() 一起使用

為陣列指定 $slice 投影。

範例

query.slice('comments', 5); // Returns the first 5 comments
query.slice('comments', -5); // Returns the last 5 comments
query.slice('comments', [10, 5]); // Returns the first 5 comments after the 10-th
query.where('comments').slice(5); // Returns the first 5 comments
query.where('comments').slice([-10, 5]); // Returns the first 5 comments after the 10-th to last

注意：如果要分割的元素數的絕對值大於陣列中的元素數，則將會傳回所有陣列元素。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', 20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', -20); // Returns [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

注意：如果要跳過的元素數為正數且大於陣列中的元素數，則將會傳回空陣列。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', [20, 5]); // Returns []

注意：如果要跳過的元素數為負數且其絕對值大於陣列中的元素數，則起始位置為陣列的開頭。

 // Given `arr`: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 query.slice('arr', [-20, 5]); // Returns [1, 2, 3, 4, 5]

設定排序順序

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

如果傳遞了字串，則必須是空格分隔的路徑名稱清單。除非路徑名稱有 - 字首，否則每個路徑的排序順序為遞增，這將被視為遞減。

範例

// sort by "field" ascending and "test" descending
query.sort({ field: 'asc', test: -1 });

// equivalent
query.sort('field -test');

// also possible is to use a array with array key-value pairs
query.sort([['field', 'asc']]);

注意

不能與 distinct() 一起使用

設定尾部選項（用於 capped 集合）。

範例

query.tailable(); // true
query.tailable(true);
query.tailable(false);

// Set both `tailable` and `awaitData` options
query.tailable({ awaitData: true });

注意

不能與 distinct() 一起使用

執行查詢，返回一個 Promise，該 Promise 將以 doc(s) 解析，或以錯誤拒絕。

更多關於 JavaScript 中的 then()。

將此查詢轉換為自定義的可重用查詢建構子，並保留所有引數和選項。

範例

// Create a query for adventure movies and read from the primary
// node in the replica-set unless it is down, in which case we'll
// read from a secondary node.
const query = Movie.find({ tags: 'adventure' }).read('primaryPreferred');

// create a custom Query constructor based off these settings
const Adventure = query.toConstructor();

// further narrow down our query results while still using the previous settings
await Adventure().where({ name: /^Life/ }).exec();

// since Adventure is a stand-alone constructor we can also add our own
// helper methods and getters without impacting global queries
Adventure.prototype.startsWith = function (prefix) {
  this.where({ name: new RegExp('^' + prefix) })
  return this;
}
Object.defineProperty(Adventure.prototype, 'highlyRated', {
  get: function () {
    this.where({ rating: { $gt: 4.5 }});
    return this;
  }
})
await Adventure().highlyRated.startsWith('Life').exec();

執行函式 fn，並將 fn 的回傳值視為查詢要解析的新值。

您傳遞給 transform() 的任何函式都將在任何 post hook 之後執行。

範例

const res = await MyModel.findOne().transform(res => {
  // Sets a `loadedAt` property on the doc that tells you the time the
  // document was loaded.
  return res == null ?
    res :
    Object.assign(res, { loadedAt: new Date() });
});

宣告和/或執行此查詢作為 updateMany() 操作。MongoDB 將更新符合 filter 的所有文件（而不僅僅是第一個）。

注意 updateMany 不會觸發更新中介軟體。請改用 `pre('updateMany')` 和 `post('updateMany')`。

範例

const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
res.n; // Number of documents matched
res.nModified; // Number of documents modified

此函數會觸發以下中間件。

• updateMany()

宣告和/或執行此查詢作為 updateOne() 操作。MongoDB 將更新符合 filter 的第一個文件。

• 如果您想要覆寫整個文件，而不是使用像 $set 這樣的 原子運算子，請使用 replaceOne()。

注意 updateOne 不會觸發更新中介軟體。請改用 `pre('updateOne')` 和 `post('updateOne')`。

範例

const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
res.acknowledged; // Indicates if this write result was acknowledged. If not, then all other members of this result will be undefined.
res.matchedCount; // Number of documents that matched the filter
res.modifiedCount; // Number of documents that were modified
res.upsertedCount; // Number of documents that were upserted
res.upsertedId; // Identifier of the inserted document (if an upsert took place)

此函數會觸發以下中間件。

• updateOne()

設定指定的 mongod 伺服器數量，或 mongod 伺服器的標籤集，這些伺服器必須先確認此寫入，此寫入才被視為成功。此選項僅適用於寫入資料庫的操作。

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

預設為 schema 的 writeConcern.w 選項

範例

// The 'majority' option means the `deleteOne()` promise won't resolve
// until the `deleteOne()` has propagated to the majority of the replica set
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  w('majority');

指定一個用於鏈接的 path。

範例

// instead of writing:
User.find({age: {$gte: 21, $lte: 65}});

// we can instead write:
User.where('age').gte(21).lte(65);

// passing query conditions is permitted
User.find().where({ name: 'vonderful' })

// chaining
User
.where('age').gte(21).lte(65)
.where('name', /^vonderful/i)
.where('friends').slice(10)
.exec()

為地理空間查詢定義 $within 或 $geoWithin 引數。

範例

query.where(path).within().box()
query.where(path).within().circle()
query.where(path).within().geometry()

query.where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true });
query.where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] });
query.where('loc').within({ polygon: [[],[],[],[]] });

query.where('loc').within([], [], []) // polygon
query.where('loc').within([], []) // box
query.where('loc').within({ type: 'LineString', coordinates: [...] }); // geometry

必須 在 where() 之後使用。

注意

從 Mongoose 3.7 開始，查詢總是使用 $geoWithin。要更改此行為，請參閱 Query.use$geoWithin。

注意

在 Mongoose 3.7 中，within 從 getter 變更為函式。如果您需要舊的語法，請使用 此。

為此查詢設定 3 個寫入關注參數。

• w：設定指定的 mongod 伺服器數量，或 mongod 伺服器的標籤集，這些伺服器必須先確認此寫入，此寫入才被視為成功。
• j：布林值，設定為 true 以請求確認此操作已持久保存到 MongoDB 的磁碟日誌。
• wtimeout：如果 w > 1，則在操作失敗之前，等待此寫入在副本集中傳播的最長時間。預設值為 0，表示沒有逾時。

此選項僅適用於寫入資料庫的操作

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

預設為 schema 的 writeConcern 選項

範例

// The 'majority' option means the `deleteOne()` promise won't resolve
// until the `deleteOne()` has propagated to the majority of the replica set
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  writeConcern({ w: 'majority' });

如果 w > 1，則在操作失敗之前，等待此寫入在副本集中傳播的最長時間。預設值為 0，表示沒有逾時。

此選項僅適用於寫入資料庫的操作

• deleteOne()
• deleteMany()
• findOneAndDelete()
• findOneAndReplace()
• findOneAndUpdate()
• updateOne()
• updateMany()

預設為 schema 的 writeConcern.wtimeout 選項

範例

// The `deleteOne()` promise won't resolve until this `deleteOne()` has
// propagated to at least `w = 2` members of the replica set. If it takes
// longer than 1 second, this `deleteOne()` will fail.
await mongoose.model('Person').
  deleteOne({ name: 'Ned Stark' }).
  w(2).
  wtimeout(1000);

返回一個 asyncIterator，用於 for/await/of 迴圈。此函式僅適用於 find() 查詢。您無需顯式呼叫此函式，JavaScript 執行時會為您呼叫。

範例

for await (const doc of Model.aggregate([{ $sort: { name: 1 } }])) {
  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。

返回此查詢的字串表示。

更多關於 JavaScript 中的 toString()。

範例

const q = Model.find();
console.log(q); // Prints "Query { find }"

選擇不使用 $geoWithin 的標誌。

mongoose.Query.use$geoWithin = false;

MongoDB 2.4 棄用了 $within 的使用，並以 $geoWithin 取代。Mongoose 預設使用 $geoWithin（與 $within 100% 向後相容）。如果您執行的是較舊版本的 MongoDB，請將此標誌設定為 false，以便您的 within() 查詢繼續工作。