模型 (Model)

模型是一個類別，是您與 MongoDB 互動的主要工具。模型的實例稱為 文件。

在 Mongoose 中，「模型」一詞指的是 mongoose.Model 類別的子類別。您不應直接使用 mongoose.Model 類別。如下所示，mongoose.model() 和 connection.model() 函數會建立 mongoose.Model 的子類別。

範例

// `UserModel` is a "Model", a subclass of `mongoose.Model`.
const UserModel = mongoose.model('User', new Schema({ name: String }));

// You can use a Model to create new documents using `new`:
const userDoc = new UserModel({ name: 'Foo' });
await userDoc.save();

// You also use a model to create queries:
const userFromDb = await UserModel.findOne({ name: 'Foo' });

建立一個 Query 並指定一個 $where 條件。

有時您需要使用 JavaScript 表達式在 mongodb 中查詢內容。您可以使用 find({ $where: javascript }) 執行此操作，或者您可以使用 mongoose 捷徑方法 $where 通過 Query 鏈或從您的 mongoose 模型中執行。

Blog.$where('this.username.indexOf("val") !== -1').exec(function (err, docs) {});

對模型的集合執行聚合。

如果傳遞了 callback，則會執行 aggregate 並傳回 Promise。如果未傳遞回呼，則會傳回 aggregate 本身。

此函數會觸發以下中介軟體。

• aggregate()

範例

// Find the max balance of all accounts
const res = await Users.aggregate([
  { $group: { _id: null, maxBalance: { $max: '$balance' }}},
  { $project: { _id: 0, maxBalance: 1 }}
]);

console.log(res); // [ { maxBalance: 98000 } ]

// Or use the aggregation pipeline builder.
const res = await Users.aggregate().
  group({ _id: null, maxBalance: { $max: '$balance' } }).
  project('-id maxBalance').
  exec();
console.log(res); // [ { maxBalance: 98 } ]

注意

• Mongoose 不會將聚合管線轉換為模型的綱要，因為 $project 和 $group 運算子允許在管線的任何階段重新定義文件的「形狀」，這可能會使文件處於不相容的格式。您可以使用mongoose-cast-aggregation 外掛程式為聚合管線啟用最小轉換。
• 傳回的文件是普通的 javascript 物件，而不是 mongoose 文件（因為可以傳回任何形狀的文件）。

更多關於聚合的資訊

• Mongoose Aggregate
• Mongoose Aggregate 簡介
• MongoDB 聚合文件

將預設值套用至給定的文件或 POJO。

將此模型的虛擬欄位套用至給定的 POJO。虛擬欄位會以 POJO 作為上下文 this 執行。

範例

const userSchema = new Schema({ name: String });
userSchema.virtual('upper').get(function() { return this.name.toUpperCase(); });
const User = mongoose.model('User', userSchema);

const obj = { name: 'John' };
User.applyVirtuals(obj);
obj.name; // 'John'
obj.upper; // 'JOHN', Mongoose applied the return value of the virtual to the given object

取得文件陣列、取得變更，並根據文件是否為新文件，或是否已變更，在資料庫中插入/更新文件。

bulkSave 在底層使用 bulkWrite，因此在處理大量文件 (10K+) 時最有用

bulkSave() 在以下情況下擲回錯誤

• 其中一個提供的文件未通過驗證。在這種情況下，bulkSave() 不會傳送 bulkWrite()，而是擲回第一個驗證錯誤。
• bulkWrite() 失敗（例如，由於無法連線到 MongoDB 或由於重複的鍵錯誤）
• bulkWrite() 沒有插入或更新任何文件。在這種情況下，bulkSave() 將擲回 DocumentNotFound 錯誤。

請注意，如果只有部分 save() 呼叫成功，則 bulkSave() 不會擲回錯誤。

在一個指令中向 MongoDB 伺服器發送多個 insertOne、updateOne、updateMany、replaceOne、deleteOne 和/或 deleteMany 操作。這比發送多個獨立操作（例如，如果您使用 create()）更快，因為使用 bulkWrite() 只會與 MongoDB 進行一次往返。

Mongoose 會對您提供的所有操作執行類型轉換。唯一的例外是將 updateOne 或 updateMany 的 update 運算子設定為管道：Mongoose 不會轉換更新管道。

此函數不會觸發任何中介軟體，包括 save() 和 update()。如果您需要為每個文件觸發 save() 中介軟體，請改用 create()。

範例

Character.bulkWrite([
  {
    insertOne: {
      document: {
        name: 'Eddard Stark',
        title: 'Warden of the North'
      }
    }
  },
  {
    updateOne: {
      filter: { name: 'Eddard Stark' },
      // If you were using the MongoDB driver directly, you'd need to do
      // `update: { $set: { title: ... } }` but mongoose adds $set for
      // you.
      update: { title: 'Hand of the King' }
    }
  },
  {
    deleteOne: {
      filter: { name: 'Eddard Stark' }
    }
  }
]).then(res => {
 // Prints "1 1 1"
 console.log(res.insertedCount, res.modifiedCount, res.deletedCount);
});

// Mongoose does **not** cast update pipelines, so no casting for the `update` option below.
// Mongoose does still cast `filter`
await Character.bulkWrite([{
  updateOne: {
    filter: { name: 'Annika Hansen' },
    update: [{ $set: { name: 7 } }] // Array means update pipeline, so Mongoose skips casting
  }
}]);

支援的操作包括

• insertOne
• updateOne
• updateMany
• deleteOne
• deleteMany
• replaceOne

將給定的 POJO 轉換為模型的綱要

範例

const Test = mongoose.model('Test', Schema({ num: Number }));

const obj = Test.castObject({ num: '42' });
obj.num; // 42 as a number

Test.castObject({ num: 'not a number' }); // Throws a ValidationError

刪除此模型綱要中未定義的所有索引。由 syncIndexes() 使用。

傳回的 Promise 會解析為已刪除索引名稱的列表，以陣列形式呈現

計算資料庫集合中符合 filter 的文件數量。

範例

Adventure.countDocuments({ type: 'jungle' }, function (err, count) {
  console.log('there are %d jungle adventures', count);
});

如果您想計算大型集合中的所有文件，請改用 estimatedDocumentCount() 函數。如果您呼叫 countDocuments({})，MongoDB 將始終執行完整的集合掃描，而不會使用任何索引。

countDocuments() 函數與 count() 類似，但有一些 countDocuments() 不支援的運算子。以下是 count() 支援但 countDocuments() 不支援的運算子，以及建議的替換方式

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

將一個或多個文件儲存到資料庫的快捷方式。MyModel.create(docs) 會對 docs 中的每個文件執行 new MyModel(doc).save()。

此函數會觸發以下中介軟體。

• save()

範例

// Insert one new `Character` document
await Character.create({ name: 'Jean-Luc Picard' });

// Insert multiple new `Character` documents
await Character.create([{ name: 'Will Riker' }, { name: 'Geordi LaForge' }]);

// Create a new character within a transaction. Note that you **must**
// pass an array as the first parameter to `create()` if you want to
// specify options.
await Character.create([{ name: 'Jean-Luc Picard' }], { session });

為此模型建立集合。預設情況下，如果未指定任何索引，mongoose 將不會為模型建立集合，直到建立任何文件。使用此方法明確建立集合。

注意 1：您可能需要在啟動交易之前呼叫此方法。請參閱 https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-operations

注意 2：如果您的綱要包含索引或唯一欄位，則不必呼叫此方法。在這種情況下，只需使用 Model.init() 即可

範例

const userSchema = new Schema({ name: String })
const User = mongoose.model('User', userSchema);

User.createCollection().then(function(collection) {
  console.log('Collection is created!');
});

與 ensureIndexes() 類似，除了它使用 createIndex 函數。

建立 Atlas 搜尋索引。此函數僅在連線到 MongoDB Atlas 時有效。

範例

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.createSearchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });

模型使用的連線實例。

從集合中刪除符合 conditions 的所有文件。它會傳回一個具有 deletedCount 屬性的物件，其中包含已刪除的文件數量。行為類似於 remove()，但無論 single 選項如何，都會刪除所有符合 conditions 的文件。

範例

await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }); // returns {deletedCount: x} where x is the number of documents deleted.

注意

此函數會觸發 deleteMany 查詢掛鉤。請閱讀 中介軟體文件以瞭解更多資訊。

從集合中刪除第一個符合 conditions 的文件。它會傳回一個具有 deletedCount 屬性的物件，指示已刪除的文件數量。行為類似於 remove()，但無論 single 選項如何，最多刪除一個文件。

範例

await Character.deleteOne({ name: 'Eddard Stark' }); // returns {deletedCount: 1}

注意

此函數會觸發 deleteOne 查詢掛鉤。請閱讀 中介軟體文件以瞭解更多資訊。

執行 Model.syncIndexes() 的試運行，傳回如果您要執行 syncIndexes()，則 syncIndexes() 將會刪除和建立的索引。

範例

const { toDrop, toCreate } = await Model.diffIndexes();
toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create

新增辨別器類型。

範例

function BaseSchema() {
  Schema.apply(this, arguments);

  this.add({
    name: String,
    createdAt: Date
  });
}
util.inherits(BaseSchema, Schema);

const PersonSchema = new BaseSchema();
const BossSchema = new BaseSchema({ department: String });

const Person = mongoose.model('Person', PersonSchema);
const Boss = Person.discriminator('Boss', BossSchema);
new Boss().__t; // "Boss". `__t` is the default `discriminatorKey`

const employeeSchema = new Schema({ boss: ObjectId });
const Employee = Person.discriminator('Employee', employeeSchema, 'staff');
new Employee().__t; // "staff" because of 3rd argument above

為 distinct 操作建立查詢。

範例

const query = Link.distinct('url');
query.exec();

依名稱刪除現有的 Atlas 搜尋索引。此函數僅在連線到 MongoDB Atlas 時有效。

範例

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.dropSearchIndex('test');

針對綱要中宣告的每個索引，向 mongo 發送 createIndex 指令。createIndex 指令依序發送。

範例

await Event.ensureIndexes();

完成後，此 Model 會發出 index 事件，如果發生錯誤，則會傳遞錯誤。

範例

const eventSchema = new Schema({ thing: { type: 'string', unique: true } })
const Event = mongoose.model('Event', eventSchema);

Event.on('index', function (err) {
  if (err) console.error(err); // error occurred during index creation
});

注意：不建議您在生產環境中執行此操作。索引建立可能會影響資料庫效能，具體取決於您的負載。請謹慎使用。

估計 MongoDB 集合中的文件數量。對於大型集合，使用 estimatedDocumentCount() 比使用 countDocuments() 快，因為 estimatedDocumentCount() 使用集合中繼資料，而不是掃描整個集合。

範例

const numAdventures = await Adventure.estimatedDocumentCount();

報告發生的任何錯誤的事件發射器。適用於全域錯誤處理。

範例

MyModel.events.on('error', err => console.log(err.message));

// Prints a 'CastError' because of the above handler
await MyModel.findOne({ _id: 'Not a valid ObjectId' }).catch(noop);

如果資料庫中至少存在一個符合給定 filter 的文件，則僅傳回具有 _id 的文件，否則傳回 null。

在底層，MyModel.exists({ answer: 42 }) 等效於 MyModel.findOne({ answer: 42 }).select({ _id: 1 }).lean()

範例

await Character.deleteMany({});
await Character.create({ name: 'Jean-Luc Picard' });

await Character.exists({ name: /picard/i }); // { _id: ... }
await Character.exists({ name: /riker/i }); // null

此函數會觸發以下中介軟體。

• findOne()

尋找文件。

Mongoose 會在傳送指令之前轉換 filter 以符合模型的綱要。請參閱我們的查詢轉換教學，以瞭解有關 Mongoose 如何轉換 filter 的更多資訊。

範例

// find all documents
await MyModel.find({});

// find all documents named john and at least 18
await MyModel.find({ name: 'john', age: { $gte: 18 } }).exec();

// executes, name LIKE john and only selecting the "name" and "friends" fields
await MyModel.find({ name: /john/i }, 'name friends').exec();

// passing options
await MyModel.find({ name: /john/i }, null, { skip: 10 }).exec();

依其 _id 欄位尋找單一文件。findById(id) 幾乎*等效於 findOne({ _id: id })。如果您要依文件的 _id 查詢，請使用 findById() 而不是 findOne()。

id 會根據綱要在傳送指令之前進行轉換。

此函數會觸發以下中介軟體。

• findOne()

* 除了它處理 undefined 的方式之外。如果您使用 findOne()，您會發現 findOne(undefined) 和 findOne({ _id: undefined }) 等效於 findOne({}) 並傳回任意文件。但是，mongoose 會將 findById(undefined) 轉換為 findOne({ _id: null })。

範例

// Find the adventure with the given `id`, or `null` if not found
await Adventure.findById(id).exec();

// select only the adventures name and length
await Adventure.findById(id, 'name length').exec();

依文件的 _id 欄位發出 MongoDB findOneAndDelete() 指令。換句話說，findByIdAndDelete(id) 是 findOneAndDelete({ _id: id }) 的簡寫。

此函數會觸發以下中介軟體。

• findOneAndDelete()

透過文檔的 _id 欄位發出 mongodb findOneAndUpdate 命令。findByIdAndUpdate(id, ...) 等效於 findOneAndUpdate({ _id: id }, ...)。

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

此函數會觸發以下中介軟體。

• findOneAndUpdate()

範例

A.findByIdAndUpdate(id, update, options)  // returns Query
A.findByIdAndUpdate(id, update)           // returns Query
A.findByIdAndUpdate()                     // returns Query

注意

所有非 atomic 操作名稱的頂層更新鍵都會被視為設定操作。

範例

Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options)

// is sent as
Model.findByIdAndUpdate(id, { $set: { name: 'jason bourne' }}, options)

注意

findOneAndX 和 findByIdAndX 函數支援有限的驗證。您可以透過設定 runValidators 選項來啟用驗證。

如果您需要完整的驗證，請使用傳統方法，先檢索文檔。

const doc = await Model.findById(id)
doc.name = 'jason bourne';
await doc.save();

尋找一個文檔。

在發送命令之前，conditions 會強制轉換為它們各自的 SchemaTypes。

注意：conditions 是可選的，如果 conditions 為 null 或未定義，Mongoose 將向 MongoDB 發送空的 findOne 命令，這將返回任意文檔。如果您要透過 _id 查詢，請改用 findById()。

範例

// Find one adventure whose `country` is 'Croatia', otherwise `null`
await Adventure.findOne({ country: 'Croatia' }).exec();

// Model.findOne() no longer accepts a callback

// Select only the adventures name and length
await Adventure.findOne({ country: 'Croatia' }, 'name length').exec();

發出 MongoDB findOneAndDelete() 命令。

找到符合的文檔，將其移除，並返回找到的文檔（如果有）。

此函數會觸發以下中介軟體。

• findOneAndDelete()

範例

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

findOneAndX 和 findByIdAndX 函數支援有限的驗證。您可以透過設定 runValidators 選項來啟用驗證。

如果您需要完整的驗證，請使用傳統方法，先檢索文檔。

const doc = await Model.findById(id)
doc.name = 'jason bourne';
await doc.save();

發出 MongoDB findOneAndReplace() 命令。

找到符合的文檔，將其替換為提供的文檔，並返回該文檔。

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

• findOneAndReplace()

範例

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

發出 mongodb findOneAndUpdate 命令。

找到符合的文檔，根據 update 參數更新它，傳遞任何 options，並將找到的文檔（如果有）返回給回呼。如果傳遞了 callback，則執行查詢，否則返回 Query 物件。

範例

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

注意

所有非 atomic 操作名稱的頂層更新鍵都會被視為設定操作。

範例

const query = { name: 'borne' };
Model.findOneAndUpdate(query, { name: 'jason bourne' }, options)

// is sent as
Model.findOneAndUpdate(query, { $set: { name: 'jason bourne' }}, options)

注意

findOneAndX 和 findByIdAndX 函數支援有限的驗證，您可以透過設定 runValidators 選項來啟用驗證。

如果您需要完整的驗證，請使用傳統方法，先檢索文檔。

const doc = await Model.findById(id);
doc.name = 'jason bourne';
await doc.save();

從現有的原始資料建立新文檔的快捷方式，該資料已預先儲存在資料庫中。返回的文檔最初沒有任何路徑標記為已修改。

範例

// hydrate previous data into a Mongoose document
const mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });

此函數負責根據 schema 選項初始化 MongoDB 中的基礎連線。此函數會執行下列操作

• createCollection()，除非關閉了 autoCreate 選項
• ensureIndexes()，除非關閉了 autoIndex 選項
• 如果啟用了 autoSearchIndex，則在所有 schema 搜尋索引上執行 createSearchIndex()。

當使用 mongoose.model() 或 connection.model() 建立模型時，Mongoose 會自動呼叫此函數，因此您不需要呼叫 init() 來觸發索引建立。

但是，您可能需要呼叫 init() 來取回一個 promise，該 promise 將在您的索引完成時解析。如果您需要在繼續之前等待索引建立完成，則呼叫 await Model.init() 會很有幫助。例如，如果您想在繼續測試案例之前等待唯一索引建立完成。

範例

const eventSchema = new Schema({ thing: { type: 'string', unique: true } })
// This calls `Event.init()` implicitly, so you don't need to call
// `Event.init()` on your own.
const Event = mongoose.model('Event', eventSchema);

await Event.init();
console.log('Indexes are done building!');

驗證文檔陣列並在它們全部有效時將它們插入 MongoDB 的快捷方式。此函數比 .create() 快，因為它只向伺服器發送一個操作，而不是每個文檔一個操作。

Mongoose 始終在向 MongoDB 發送 insertMany 之前驗證每個文檔。因此，如果一個文檔有驗證錯誤，則不會儲存任何文檔，除非您將 ordered 選項設定為 false。

此函數不會觸發儲存中間件。

此函數會觸發以下中介軟體。

• insertMany()

範例

const docs = await Movies.insertMany([
  { name: 'Star Wars' },
  { name: 'The Empire Strikes Back' }
]);
docs[0].name; // 'Star Wars'

// Return raw result from MongoDB
const result = await Movies.insertMany([
  { name: 'Star Wars' },
  { name: 'The Empire Strikes Back' }
], { rawResult: true });

console.log 的輔助程式。給定一個名為 'MyModel' 的模型，返回字串 'Model { MyModel }'。

範例

const MyModel = mongoose.model('Test', Schema({ name: String }));
MyModel.inspect(); // 'Model { Test }'
console.log(MyModel); // Prints 'Model { Test }'

列出目前在 MongoDB 中定義的索引。這可能與您的 schema 中定義的索引相同，也可能不同，具體取決於您是否使用autoIndex 選項以及是否手動建立索引。

列出此模型集合上的所有Atlas 搜尋索引。此函數僅在連線到 MongoDB Atlas 時有效。

範例

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);

await Customer.createSearchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });
const res = await Customer.listSearchIndexes(); // Includes `[{ name: 'test' }]`

擴展文件參照。

在 Mongoose 6 中變更：您在上面呼叫 populate() 的模型應該是「本地欄位」模型，**而非**「外部欄位」模型。

可用的頂層選項

• path：要擴展的路徑，以空格分隔
• select：要選取的選用欄位
• match：要比對的選用查詢條件
• model：要用於擴展的選用模型名稱
• options：選用的查詢選項，例如 sort、limit 等
• justOne：選用的布林值，如果為 true，Mongoose 會始終將 path 設定為文件，如果找不到任何文件，則為 null。如果為 false，Mongoose 會始終將 path 設定為陣列，如果找不到任何文件，則該陣列會是空的。預設情況下從 schema 推斷。
• strictPopulate：選用的布林值，設定為 false 以允許擴展不在 schema 中的路徑。

範例

const Dog = mongoose.model('Dog', new Schema({ name: String, breed: String }));
const Person = mongoose.model('Person', new Schema({
  name: String,
  pet: { type: mongoose.ObjectId, ref: 'Dog' }
}));

const pets = await Pet.create([
  { name: 'Daisy', breed: 'Beagle' },
  { name: 'Einstein', breed: 'Catalan Sheepdog' }
]);

// populate many plain objects
const users = [
  { name: 'John Wick', dog: pets[0]._id },
  { name: 'Doc Brown', dog: pets[1]._id }
];
await User.populate(users, { path: 'dog', select: 'name' });
users[0].dog.name; // 'Daisy'
users[0].dog.breed; // undefined because of `select`

如果沒有指定 name，則回傳用於建立此文件的模型實例。如果指定了 name，則回傳具有指定 name 的模型。

範例

const doc = new Tank({});
doc.$model() === Tank; // true
await doc.$model('User').findById(id);

在呼叫 save() 時要附加到查詢的其他屬性，且 isNew 為 false。

模型使用的基礎 Mongoose 實例。

如果這是鑑別器模型，則 baseModelName 是基礎模型的名稱。

此模型使用的集合實例。Mongoose 集合是 [MongoDB Node.js 驅動程式集合](MongoDB Node.js 驅動程式集合)的精簡封裝。使用 Model.collection 表示您繞過了 Mongoose 中介軟體、驗證和轉換。

此屬性為唯讀。修改此屬性不會有任何作用。

模型使用的集合。

模型使用的連線。

從資料庫中刪除此文件。

範例

await product.deleteOne();
await Product.findById(product._id); // null

此模型的已註冊鑑別器。

表示我們希望遞增此文件的版本。

範例

const doc = await Model.findById(id);
doc.increment();
await doc.save();

如果沒有指定 name，則回傳用於建立此文件的模型實例。如果指定了 name，則回傳具有指定 name 的模型。

範例

const doc = new Tank({});
doc.$model() === Tank; // true
await doc.$model('User').findById(id);

模型的名稱

如果 document.isNew 為 true，則將新文件插入資料庫以儲存此文件，如果 isNew 為 false，則只傳送具有已修改路徑的 updateOne 作業。

範例

product.sold = Date.now();
product = await product.save();

如果儲存成功，則回傳的 Promise 會以儲存的文件完成。

範例

const newProduct = await product.save();
newProduct === product; // true

在此模型編譯後，套用對此模型 schema 所做的變更。預設情況下，在模型編譯後將虛擬屬性和其他屬性新增到 schema 不會有任何作用。呼叫此函式以套用稍後新增的虛擬屬性和屬性。

範例

const schema = new mongoose.Schema({ field: String });
const TestModel = mongoose.model('Test', schema);
TestModel.schema.virtual('myVirtual').get(function() {
  return this.field + ' from myVirtual';
});
const doc = new TestModel({ field: 'Hello' });
doc.myVirtual; // undefined

TestModel.recompileSchema();
doc.myVirtual; // 'Hello from myVirtual'

使用指定的文件取代現有的文件 (不使用像 $set 的原子運算子)。

範例

const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

此函數會觸發以下中介軟體。

• replaceOne()

模型使用的 Schema。

需要 MongoDB >= 3.6.0。 啟動 MongoDB 會話，以獲得因果一致性、可重試寫入和交易等好處。

呼叫 MyModel.startSession() 等同於呼叫 MyModel.db.startSession()。

此函式不會觸發任何中介軟體。

範例

const session = await Person.startSession();
let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
await doc.remove();
// `doc` will always be null, even if reading from a replica set
// secondary. Without causal consistency, it is possible to
// get a doc back from the below query if the query reads from a
// secondary that is experiencing replication lag.
doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });

使 MongoDB 中的索引與此模型 schema 中定義的索引相符。此函式會刪除任何未在此模型 schema 中定義的索引 (_id 索引除外)，並建立您 schema 中但 MongoDB 中沒有的任何索引。

如需詳細資訊，請參閱簡介部落格文章。

範例

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.collection.createIndex({ age: 1 }); // Index is not in schema
// Will drop the 'age' index and create an index on `name`
await Customer.syncIndexes();

您應該小心在重負載下的生產應用程式上執行 syncIndexes()，因為索引建置是昂貴的操作，且非預期的索引刪除可能會導致效能降低。在執行 syncIndexes() 之前，您可以使用diffIndexes() 函式來檢查 syncIndexes() 將會刪除和建立哪些索引。

範例

const { toDrop, toCreate } = await Model.diffIndexes();
toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create

轉換任何別名欄位/條件，讓最終的查詢或文件物件是純的

範例

await Character.find(Character.translateAliases({
   '名': 'Eddard Stark' // Alias for 'name'
});

預設情況下，translateAliases() 會使用別名欄位覆寫原始欄位。因此，如果 n 是 name 的別名，則 { n: 'alias', name: 'raw' } 會解析為 { name: 'alias' }。但是，如果存在可能衝突的路徑，您可以設定 errorOnDuplicates 選項來擲回錯誤。查詢的 translateAliases 選項使用 errorOnDuplicates。

注意

只轉換物件類型的引數，其他任何引數都回傳原始值

與 updateOne() 相同，但無論 multi 選項的值為何，MongoDB 都會更新符合 filter 的所有文件 (而不是只有第一個)。

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

範例

const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation. This may be false if Mongoose did not send an update to the server because the update was empty.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

此函數會觸發以下中介軟體。

• updateMany()

只更新符合 filter 的第一個文件。

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

範例

const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation. This may be false if Mongoose did not send an update to the server because the update was empty.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

此函數會觸發以下中介軟體。

• updateOne()

更新現有的 Atlas 搜尋索引。此函式只在連線至 MongoDB Atlas 時有效。

範例

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.updateSearchIndex('test', { mappings: { dynamic: true } });

根據此模型的 schema 轉換和驗證指定的物件，並將指定的 context 傳遞給自訂驗證器。

範例

const Model = mongoose.model('Test', Schema({
  name: { type: String, required: true },
  age: { type: Number, required: true }
});

try {
  await Model.validate({ name: null }, ['name'])
} catch (err) {
  err instanceof mongoose.Error.ValidationError; // true
  Object.keys(err.errors); // ['name']
}

需要執行 MongoDB 3.6.0 或更高版本的副本集。 使用 MongoDB 變更串流監看底層集合的變更。

此函數不會觸發任何中介軟體。特別是，它不會觸發聚合中介軟體。

ChangeStream 物件是一個事件發射器，它會發射以下事件：

• 'change'：發生變更，請參閱以下範例
• 'error'：發生無法復原的錯誤。特別是，如果變更串流失去與副本集主節點的連線，目前會發生錯誤。請追蹤 此 GitHub 問題以獲取更新。
• 'end'：如果底層串流已關閉，則會發射此事件
• 'close'：如果底層串流已關閉，則會發射此事件

範例

const doc = await Person.create({ name: 'Ned Stark' });
const changeStream = Person.watch().on('change', change => console.log(change));
// Will print from the above `console.log()`:
// { _id: { _data: ... },
//   operationType: 'delete',
//   ns: { db: 'mydb', coll: 'Person' },
//   documentKey: { _id: 5a51b125c5500f5aa094c7bd } }
await doc.remove();

建立一個查詢 (Query)，套用傳遞的條件，並傳回該查詢。

例如，我們可以寫成這樣：

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

而不是寫成這樣：

User.where('age').gte(21).lte(65).exec();

由於 Query 類別也支援 where，您可以繼續鏈式呼叫

User
.where('age').gte(21).lte(65)
.where('name', /^b/i)
... etc