文件

如果給定的路徑未填充，則拋出錯誤

範例

const doc = await Model.findOne().populate('author');

doc.$assertPopulated('author'); // does not throw
doc.$assertPopulated('other path'); // throws an error

// Manually populate and assert in one call. The following does
// `doc.$set({ likes })` before asserting.
doc.$assertPopulated('likes', { likes });

清除文件的已修改路徑。

範例

const doc = await TestModel.findOne();

doc.name = 'test';
doc.$isModified('name'); // true

doc.$clearModifiedPaths();
doc.name; // 'test', `$clearModifiedPaths()` does **not** modify the document's data, only change tracking

傳回此文件的副本，其中包含 _doc 和 $__ 的深度複製。

建立此文件內部變更追蹤狀態的快照。您稍後可以使用 $restoreModifiedPathsSnapshot() 重設此文件的變更追蹤狀態。

範例

const doc = await TestModel.findOne();
const snapshot = doc.$createModifiedPathsSnapshot();

包含目前驗證 $errors 的雜湊。

取得所有子文件 (使用 bfs)

取得與此文件相關聯的所有已填充文件。

不要在此路徑上執行驗證或將變更持久保存到此路徑。

範例

doc.foo = null;
doc.$ignore('foo');
doc.save(); // changes to foo will not be persisted and validators won't be run

將 path 上的數值遞增給定的 val。當您在此文件上呼叫 save() 時，Mongoose 將會傳送 $inc 而不是 $set。

範例

const schema = new Schema({ counter: Number });
const Test = db.model('Test', schema);

const doc = await Test.create({ counter: 0 });
doc.$inc('counter', 2);
await doc.save(); // Sends a `{ $inc: { counter: 2 } }` to MongoDB
doc.counter; // 2

doc.counter += 2;
await doc.save(); // Sends a `{ $set: { counter: 2 } }` to MongoDB

.init 的別名

檢查路徑是否設定為其預設值。

範例

MyModel = mongoose.model('test', { name: { type: String, default: 'Val '} });
const m = new MyModel();
m.$isDefault('name'); // true

Getter/setter，決定是否已移除文件。

範例

const product = await product.remove();
product.$isDeleted(); // true
product.remove(); // no-op, doesn't send anything to the db

product.$isDeleted(false);
product.$isDeleted(); // false
product.remove(); // will execute a remove against the db

如果給定的路徑為 null 或僅包含空物件，則傳回 true。這有助於判斷此子文件是否會被 minimize 選項 移除。

範例

const schema = new Schema({ nested: { foo: String } });
const Model = mongoose.model('Test', schema);
const doc = new Model({});
doc.$isEmpty('nested'); // true
doc.nested.$isEmpty(); // true

doc.nested.foo = 'bar';
doc.$isEmpty('nested'); // false
doc.nested.$isEmpty(); // false

.isModified 的別名

布林值旗標，指定文件是否為新的。如果您使用 new 建立文件，則此文件將被視為「新的」。$isNew 是 Mongoose 如何判斷 save() 應該使用 insertOne() 建立新文件還是使用 updateOne() 更新現有文件。

範例

const user = new User({ name: 'John Smith' });
user.$isNew; // true

await user.save(); // Sends an `insertOne` to MongoDB

另一方面，如果您使用 findOne() 或其他 查詢操作 從資料庫載入現有文件，$isNew 將會是 false。

範例

const user = await User.findOne({ name: 'John Smith' });
user.$isNew; // false

在 save() 成功後，Mongoose 會立即將 $isNew 設定為 false。這表示 Mongoose 會在 post('save') hook 執行之前將 $isNew 設定為 false。在 post('save') hook 中，如果 save() 成功，$isNew 將會是 false。

範例

userSchema.post('save', function() {
  this.$isNew; // false
});
await User.create({ name: 'John Smith' });

對於子文件，如果父項的 $isNew 設定為 true，或者如果您建立新的子文件，則 $isNew 為 true。

範例

// Assume `Group` has a document array `users`
const group = await Group.findOne();
group.users[0].$isNew; // false

group.users.push({ name: 'John Smith' });
group.users[1].$isNew; // true

您可以用於在文件上儲存屬性的空物件。這對於將資料傳遞給中介軟體而不會與 Mongoose 內部發生衝突非常方便。

範例

schema.pre('save', function() {
  // Mongoose will set `isNew` to `false` if `save()` succeeds
  this.$locals.wasNew = this.isNew;
});

schema.post('save', function() {
  // Prints true if `isNew` was set before `save()`
  console.log(this.$locals.wasNew);
});

將路徑標記為有效，並移除現有的驗證錯誤。

一個字串，包含 Mongoose 目前在此文件上執行的操作。可以是 null、'save'、'validate' 或 'remove'。

範例

const doc = new Model({ name: 'test' });
doc.$op; // null

const promise = doc.save();
doc.$op; // 'save'

await promise;
doc.$op; // null

parent() 的別名。如果此文件是子文件或已填充文件，則傳回文件的父項。否則傳回 undefined。

.populated 的別名。

將此文件的變更追蹤狀態還原為給定的快照。請注意，$restoreModifiedPathsSnapshot() 不會修改文件的屬性，只會重設變更追蹤狀態。

當編寫需要還原變更追蹤的 自訂交易包裝函式時，此方法特別有用。

範例

const doc = await TestModel.findOne();
const snapshot = doc.$createModifiedPathsSnapshot();

doc.name = 'test';
doc.$restoreModifiedPathsSnapshot(snapshot);
doc.$isModified('name'); // false because `name` was not modified when snapshot was taken
doc.name; // 'test', `$restoreModifiedPathsSnapshot()` does **not** modify the document's data, only change tracking

此文件相關聯工作階段的 getter/setter。用於在您 save() 從具有相關工作階段的查詢中取得的文件時自動設定 session。

範例

const session = MyModel.startSession();
const doc = await MyModel.findOne().session(session);
doc.$session() === session; // true
doc.$session(null);
doc.$session() === null; // true

如果這是頂層文件，則設定工作階段會傳播到所有子文件。

為避免衝突，在內部使用 set() 的別名

此文件在使用 save() 和 bulkSave() 時是否會預設套用時間戳記的 getter/setter。

範例

const TestModel = mongoose.model('Test', new Schema({ name: String }, { timestamps: true }));
const doc = new TestModel({ name: 'John Smith' });

doc.$timestamps(); // true

doc.$timestamps(false);
await doc.save(); // Does **not** apply timestamps

.validate 的別名

設定此屬性可在 Mongoose 儲存此文件且 isNew 為 false 時新增其他查詢篩選器。

範例

// Make sure `save()` never updates a soft deleted document.
schema.pre('save', function() {
  this.$where = { isDeleted: false };
});

取得已填充的欄位，並將其傳回未填充的狀態。

範例

Model.findOne().populate('author').exec(function (err, doc) {
  console.log(doc.author.name); // Dr.Seuss
  console.log(doc.depopulate('author'));
  console.log(doc.author); // '5144cf8050f071d979c118a7'
})

如果未提供路徑，則所有已填充的欄位都會傳回其未填充的狀態。

傳回已直接修改的路徑清單。直接修改的路徑是您明確設定的路徑，無論是透過 doc.foo = 'bar'、Object.assign(doc, { foo: 'bar' }) 或 doc.set('foo', 'bar')。

路徑 a 可能在 modifiedPaths() 中，但不在 directModifiedPaths() 中，因為 a 的子項已直接修改。

範例

const schema = new Schema({ foo: String, nested: { bar: String } });
const Model = mongoose.model('Test', schema);
await Model.create({ foo: 'original', nested: { bar: 'original' } });

const doc = await Model.findOne();
doc.nested.bar = 'modified';
doc.directModifiedPaths(); // ['nested.bar']
doc.modifiedPaths(); // ['nested', 'nested.bar']

如果此文件等於另一個文件，則傳回 true。

當文件的 _id 匹配時，則視為相等，除非兩個文件都沒有 _id，在這種情況下，此函數會退而使用 deepEqual()。

包含目前驗證錯誤的雜湊。

傳回路徑的值。

範例

// path
doc.get('age') // 47

// dynamic casting to a string
doc.get('age', String) // "47"

傳回文件中發生的變更，其格式將會傳送到 MongoDB。

範例

const userSchema = new Schema({
  name: String,
  age: Number,
  country: String
});
const User = mongoose.model('User', userSchema);
const user = await User.create({
  name: 'Hafez',
  age: 25,
  country: 'Egypt'
});

// returns an empty object, no changes happened yet
user.getChanges(); // { }

user.country = undefined;
user.age = 26;

user.getChanges(); // { $set: { age: 26 }, { $unset: { country: 1 } } }

await user.save();

user.getChanges(); // { }

修改 getChanges() 傳回的物件不會影響文件的變更追蹤狀態。即使您 delete user.getChanges().$set，Mongoose 仍會傳送 $set 到伺服器。

此文件的 _id 的字串版本。

注意

此 getter 預設存在於所有文件中。可以在建構時將其 Schema 的 id 選項 設定為 false 來停用此 getter。

new Schema({ name: String }, { id: false });

初始化文件，不使用 setter 或標記任何已修改的內容。

在從 mongodb 傳回文件後，會在內部呼叫。通常，您不需要自行呼叫此函數。

此函數會觸發 init 中介軟體。請注意，init 鉤子是同步的。

console.log 的輔助函式

將路徑標記為無效，導致驗證失敗。

errorMsg 引數將會成為 ValidationError 的訊息。

value 引數 (如果傳遞) 將可透過 ValidationError.value 屬性取得。

doc.invalidate('size', 'must be less than 20', 14);

doc.validate(function (err) {
  console.log(err)
  // prints
  { message: 'Validation failed',
    name: 'ValidationError',
    errors:
     { size:
        { message: 'must be less than 20',
          name: 'ValidatorError',
          path: 'size',
          type: 'user defined',
          value: 14 } } }
})

如果 path 是直接設定且已修改，則傳回 true，否則傳回 false。

範例

doc.set('documents.0.title', 'changed');
doc.isDirectModified('documents.0.title') // true
doc.isDirectModified('documents') // false

檢查是否明確選取了 path。如果沒有投影，則一律傳回 true。

範例

Thing.findOne().select('nested.name').exec(function (err, doc) {
   doc.isDirectSelected('nested.name') // true
   doc.isDirectSelected('nested.otherName') // false
   doc.isDirectSelected('nested')  // false
})

檢查 path 是否處於 init 狀態，也就是說，它是透過 Document#init() 設定且從未修改過。

如果任何給定的路徑已修改，則傳回 true，否則傳回 false。如果沒有引數，則如果此文件中的任何路徑已修改，則傳回 true。

如果給定 path，則檢查路徑或任何包含 path 作為其路徑鏈一部分的完整路徑是否已修改。

範例

doc.set('documents.0.title', 'changed');
doc.isModified()                      // true
doc.isModified('documents')           // true
doc.isModified('documents.0.title')   // true
doc.isModified('documents otherProp') // true
doc.isDirectModified('documents')     // false

$isNew 的舊版別名。

檢查是否在初始化此文件的來源查詢中選取了 path。

範例

const doc = await Thing.findOne().select('name');
doc.isSelected('name') // true
doc.isSelected('age')  // false

將路徑標記為有待寫入資料庫的變更。

當使用 混合類型時，非常有用。

範例

doc.mixed.type = 'changed';
doc.markModified('mixed.type');
doc.save() // changes to mixed.type are now persisted

傳回已修改的路徑清單。

使用 obj 的值覆寫此文件中的所有值，但不可變的屬性除外。行為與 set() 類似，但它會取消設定所有不在 obj 中的屬性。

如果此文件是子文件或已填入的文件，則傳回文件的父系。如果沒有父系，則傳回原始文件。

填入現有文件上的路徑。

範例

// Given a document, `populate()` lets you pull in referenced docs
await doc.populate([
  'stories',
  { path: 'fans', sort: { name: -1 } }
]);
doc.populated('stories'); // Array of ObjectIds
doc.stories[0].title; // 'Casino Royale'
doc.populated('fans'); // Array of ObjectIds

// If the referenced doc has been deleted, `populate()` will
// remove that entry from the array.
await Story.delete({ title: 'Casino Royale' });
await doc.populate('stories'); // Empty array

// You can also pass additional query options to `populate()`,
// like projections:
await doc.populate('fans', '-email');
doc.fans[0].email // undefined because of 2nd param `select`

取得在給定 path 的填入期間使用的 _id。

範例

const doc = await Model.findOne().populate('author');

console.log(doc.author.name); // Dr.Seuss
console.log(doc.populated('author')); // '5144cf8050f071d979c118a7'

如果未填入路徑，則傳回 undefined。

傳送 replaceOne 命令，其中此文件 _id 作為查詢選取器。

有效的選項

• 與 Model.replaceOne 中相同

如果 document.isNew 為 true，則會透過將新文件插入資料庫來儲存此文件，否則會僅傳送對資料庫的修改 updateOne 操作，在後一種情況下不會取代整個文件。

範例

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

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

範例

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

文件的 schema。

設定路徑的值或多個路徑的值。別名為 .$set。

範例

// path, value
doc.set(path, value)

// object
doc.set({
    path  : value
  , path2 : {
       path  : value
    }
})

// on-the-fly cast to number
doc.set(path, value, Number)

// on-the-fly cast to string
doc.set(path, value, String)

// changing strict mode behavior
doc.set(path, value, { strict: false });

此方法的返回值會在呼叫 JSON.stringify(doc) 時使用。

此方法接受與 Document#toObject 相同的選項。若要預設將選項套用至您 schema 的每個 document，請將您的 schema toJSON 選項設定為相同的參數。

schema.set('toJSON', { virtuals: true });

toJSON() 和 toObject() 選項之間有一個差異。當您呼叫 toJSON() 時，flattenMaps 選項預設為 true，因為 JSON.stringify() 預設不會將 map 轉換為物件。當您呼叫 toObject() 時，flattenMaps 選項預設為 false。

請參閱schema 選項以取得更多關於設定 toJSON 選項預設值的資訊。

將此 document 轉換為純 JavaScript 物件 (POJO)。

為了正確儲存，Buffer 會轉換為 mongodb.Binary 的實例。

Getter/虛擬屬性

僅套用路徑 getter 的範例

doc.toObject({ getters: true, virtuals: false })

僅套用虛擬屬性 getter 的範例

doc.toObject({ virtuals: true })

同時套用路徑 getter 和虛擬屬性 getter 的範例

doc.toObject({ getters: true })

若要預設將這些選項套用至您 schema 的每個 document，請將您的 schema toObject 選項設定為相同的參數。

schema.set('toObject', { virtuals: true })

轉換

我們可能需要根據某些條件對產生的物件執行轉換，例如刪除一些敏感資訊或傳回自訂物件。在這種情況下，我們設定可選的 transform 函式。

轉換函式接收三個參數

function (doc, ret, options) {}

• doc 正在轉換的 mongoose document
• ret 已轉換的純物件表示法
• options 使用中的選項 (schema 選項或內聯傳遞的選項)

範例

// specify the transform schema option
if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  // remove the _id of every document before returning the result
  delete ret._id;
  return ret;
}

// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }

// with the transformation
doc.toObject(); // { name: 'Wreck-it Ralph' }

透過轉換，我們可以做的不僅僅是刪除屬性。我們甚至可以傳回完全自訂的新物件

if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  return { movie: ret.name }
}

// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }

// with the transformation
doc.toObject(); // { movie: 'Wreck-it Ralph' }

注意：如果轉換函式傳回 undefined，則傳回值將被忽略。

轉換也可以內聯套用，覆寫 schema 選項中設定的任何轉換。在 toObject 選項中指定的任何轉換函式也會傳播到任何子 document。

function deleteId(doc, ret, options) {
  delete ret._id;
  return ret;
}

const schema = mongoose.Schema({ name: String, docArr: [{ name: String }] });
const TestModel = mongoose.model('Test', schema);

const doc = new TestModel({ name: 'test', docArr: [{ name: 'test' }] });

// pass the transform as an inline option. Deletes `_id` property
// from both the top-level document and the subdocument.
const obj = doc.toObject({ transform: deleteId });
obj._id; // undefined
obj.docArr[0]._id; // undefined

如果您想要跳過轉換，請使用 transform: false

schema.options.toObject.hide = '_id';
schema.options.toObject.transform = function (doc, ret, options) {
  if (options.hide) {
    options.hide.split(' ').forEach(function (prop) {
      delete ret[prop];
    });
  }
  return ret;
}

const doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }

如果您在 toObject() 選項中傳遞轉換，Mongoose 會將轉換套用到頂級 document 以及 子 document。類似地，transform: false 會跳過所有子 document 的轉換。請注意，對於在 schema 中定義的轉換，此行為是不同的：如果您在 schema.options.toObject.transform 中定義轉換，則該轉換將 **不會** 套用到子 document。

const memberSchema = new Schema({ name: String, email: String });
const groupSchema = new Schema({ members: [memberSchema], name: String, email });
const Group = mongoose.model('Group', groupSchema);

const doc = new Group({
  name: 'Engineering',
  email: 'dev@mongoosejs.io',
  members: [{ name: 'Val', email: 'val@mongoosejs.io' }]
});

// Removes `email` from both top-level document **and** array elements
// { name: 'Engineering', members: [{ name: 'Val' }] }
doc.toObject({ transform: (doc, ret) => { delete ret.email; return ret; } });

轉換，就像所有這些選項一樣，也適用於 toJSON。請參閱 這篇關於 JSON.stringify() 的指南，以了解為什麼 toJSON() 和 toObject() 是獨立的函式。

請參閱schema 選項以取得更多詳細資訊。

在儲存期間，在將 document 送到資料庫之前，不會對 document 套用任何自訂選項。

console.log 的輔助函式

清除指定路徑上的已修改狀態。

範例

doc.foo = 'bar';
doc.unmarkModified('foo');
doc.save(); // changes to foo will not be persisted

傳送 updateOne 命令，並以此 document 的 _id 作為查詢選擇器。

範例

weirdCar.updateOne({$inc: {wheels:1}}, { w: 1 }, callback);

有效的選項

• 與 Model.updateOne 中的相同

執行此 document 的已註冊驗證規則。

注意

此方法會在 pre 儲存時呼叫，如果違反驗證規則，則會中止 save 並擲回錯誤。

範例

await doc.validate({ validateModifiedOnly: false, pathsToSkip: ['name', 'email']});

執行此 document 的已註冊驗證規則 (跳過非同步驗證器)。

注意

如果您需要同步驗證，此方法會很有用。

範例

const err = doc.validateSync();
if (err) {
  handleError(err);
} else {
  // validation passed
}