文档

如果给定的路径未填充，则抛出错误

示例

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 的哈希。

获取所有子文档（通过广度优先搜索）

获取与该文档关联的所有填充的文档。

不要对该路径运行验证，也不要将更改持久化到该路径。

示例

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

如果给定的路径为 nullish 或仅包含空对象，则返回 true。对于确定此子文档是否会被 最小化选项 剥离，此方法很有用。

示例

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

Mongoose 在 save() 成功后立即将 $isNew 设置为 false。这意味着 Mongoose 在 post('save') 钩子运行之前将 $isNew 设置为 false。在 post('save') 钩子中，如果 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() 的别名，在内部使用以避免冲突

Getter/Setter，用于确定此文档是否将在使用 save() 和 bulkSave() 时默认应用时间戳。

示例

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 默认存在于所有文档中。Getter 可以通过在构造时将 Schema 的 id 选项 设置为 false 来禁用。

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

在没有设置器或标记任何修改的情况下初始化文档。

在文档从 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

将路径标记为有待写入数据库的更改。

在使用 Mixed 类型时非常有用。

示例

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(s)。

示例

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

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

如果路径未填充，则返回 undefined。

使用此文档 _id 作为查询选择器发送 replaceOne 命令。

有效选项

• 与 Model.replaceOne 中的相同

通过将新文档插入数据库来保存此文档（如果 document.isNew 为 true），或者仅发送 updateOne 操作，其中包含对数据库的修改，在后一种情况下不会替换整个文档。

示例

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

如果保存成功，则返回的 promise 将使用已保存的文档来实现。

示例

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

文档的模式。

设置一个或多个路径的值。.$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 相同的选项。要默认将选项应用于模式的每个文档，请将 模式 的 toJSON 选项设置为相同的参数。

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

toJSON() 和 toObject() 选项之间有一个区别。当您调用 toJSON() 时，flattenMaps 选项 默认设置为 true，因为 JSON.stringify() 默认情况下不会将 maps 转换为对象。当您调用 toObject() 时，flattenMaps 选项默认设置为 false。

请参阅 模式选项，以获取有关设置 toJSON 选项默认值的更多信息。

将此文档转换为普通的 JavaScript 对象 (POJO）。

缓冲区被转换为 mongodb.Binary 的实例以进行正确的存储。

获取器/虚拟属性

仅应用路径获取器的示例

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

仅应用虚拟获取器的示例

doc.toObject({ virtuals: true })

应用路径和虚拟获取器的示例

doc.toObject({ getters: true })

要将这些选项默认应用于模式的每个文档，请将您的 模式 toObject 选项设置为相同的参数。

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

转换

我们可能需要根据某些条件对结果对象进行转换，例如删除一些敏感信息或返回自定义对象。在这种情况下，我们设置可选的 transform 函数。

转换函数接收三个参数

function (doc, ret, options) {}

• doc 正在转换的 Mongoose 文档
• ret 已转换的普通对象表示
• options 使用中的选项（模式选项或内联传递的选项）

示例

// 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，则返回值将被忽略。

转换也可以内联应用，覆盖模式选项中设置的任何转换。在 toObject 选项中指定的任何转换函数也会传播到任何子文档。

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 将除了顶层文档之外还将转换应用于 子文档。类似地，transform: false 会跳过所有子文档的转换。请注意，此行为与在模式中定义的转换不同：如果您在 schema.options.toObject.transform 中定义转换，则该转换将 **不会** 应用于子文档。

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() 是为什么是单独的函数。

有关更多详细信息，请查看 模式选项。

在保存期间，在文档发送到数据库之前不会对其应用任何自定义选项。

用于 console.log 的辅助函数

清除指定路径上的修改状态。

示例

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

使用此文档 _id 作为查询选择器发送 updateOne 命令。

示例

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

有效选项

• 与 Model.updateOne 中的相同

执行为此文档注册的验证规则。

注意

此方法在 pre 保存时被调用，如果验证规则被违反，保存 将中止并抛出错误。

示例

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

执行为此文档注册的验证规则（跳过异步验证器）。

注意

如果您需要同步验证，此方法很有用。

示例

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