Document

Throws an error if a given path is not populated

Example:

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

Clear the document's modified paths.

Example:

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

Returns a copy of this document with a deep clone of _doc and $__.

Creates a snapshot of this document's internal change tracking state. You can later reset this document's change tracking state using $restoreModifiedPathsSnapshot().

Example:

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

Hash containing current validation $errors.

Get all subdocs (by bfs)

Gets all populated documents associated with this document.

Don't run validation on this path or persist changes to this path.

Example:

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

Increments the numeric value at path by the given val. When you call save() on this document, Mongoose will send a $inc as opposed to a $set.

Example:

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

Alias for .init

Checks if a path is set to its default.

Example:

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

Getter/setter, determines whether the document was removed or not.

Example:

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

Returns true if the given path is nullish or only contains empty objects. Useful for determining whether this subdoc will get stripped out by the minimize option.

Example:

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

Alias of .isModified

Boolean flag specifying if the document is new. If you create a document using new, this document will be considered "new". $isNew is how Mongoose determines whether save() should use insertOne() to create a new document or updateOne() to update an existing document.

Example:

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

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

On the other hand, if you load an existing document from the database using findOne() or another query operation, $isNew will be false.

Example:

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

Mongoose sets $isNew to false immediately after save() succeeds. That means Mongoose sets $isNew to false before post('save') hooks run. In post('save') hooks, $isNew will be false if save() succeeded.

Example:

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

For subdocuments, $isNew is true if either the parent has $isNew set, or if you create a new subdocument.

Example:

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

Empty object that you can use for storing properties on the document. This is handy for passing data to middleware without conflicting with Mongoose internals.

Example:

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

Marks a path as valid, removing existing validation errors.

A string containing the current operation that Mongoose is executing on this document. May be null, 'save', 'validate', or 'remove'.

Example:

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

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

await promise;
doc.$op; // null

Alias for parent(). If this document is a subdocument or populated document, returns the document's parent. Returns undefined otherwise.

Alias of .populated.

Restore this document's change tracking state to the given snapshot. Note that $restoreModifiedPathsSnapshot() does not modify the document's properties, just resets the change tracking state.

This method is especially useful when writing custom transaction wrappers that need to restore change tracking when aborting a transaction.

Example:

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 around the session associated with this document. Used to automatically set session if you save() a doc that you got from a query with an associated session.

Example:

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

If this is a top-level document, setting the session propagates to all child docs.

Alias for set(), used internally to avoid conflicts

Getter/setter around whether this document will apply timestamps by default when using save() and bulkSave().

Example:

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

Alias of .validate

Set this property to add additional query filters when Mongoose saves this document and isNew is false.

Example:

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

Takes a populated field and returns it to its unpopulated state.

Example:

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

If the path was not provided, then all populated fields are returned to their unpopulated state.

Returns the list of paths that have been directly modified. A direct modified path is a path that you explicitly set, whether via doc.foo = 'bar', Object.assign(doc, { foo: 'bar' }), or doc.set('foo', 'bar').

A path a may be in modifiedPaths() but not in directModifiedPaths() because a child of a was directly modified.

Example:

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']

Returns true if this document is equal to another document.

Documents are considered equal when they have matching _ids, unless neither document has an _id, in which case this function falls back to using deepEqual().

Hash containing current validation errors.

Returns the value of a path.

Example:

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

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

Returns the changes that happened to the document in the format that will be sent to MongoDB.

Example:

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

Modifying the object that getChanges() returns does not affect the document's change tracking state. Even if you delete user.getChanges().$set, Mongoose will still send a $set to the server.

The string version of this documents _id.

Note:

This getter exists on all documents by default. The getter can be disabled by setting the id option of its Schema to false at construction time.

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

Hydrates this document with the data in doc. Does not run setters or mark any paths modified.

Called internally after a document is returned from MongoDB. Normally, you do not need to call this function on your own.

This function triggers init middleware. Note that init hooks are synchronous.

Helper for console.log

Marks a path as invalid, causing validation to fail.

The errorMsg argument will become the message of the ValidationError.

The value argument (if passed) will be available through the ValidationError.value property.

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

Returns true if path was directly set and modified, else false.

Example:

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

Checks if path was explicitly selected. If no projection, always returns true.

Example:

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

Checks if path is in the init state, that is, it was set by Document#init() and not modified since.

Returns true if any of the given paths is modified, else false. If no arguments, returns true if any path in this document is modified.

If path is given, checks if a path or any full path containing path as part of its path chain has been modified.

Example:

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

Legacy alias for $isNew.

Checks if path was selected in the source query which initialized this document.

Example:

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

Marks the path as having pending changes to write to the db.

Very helpful when using Mixed types.

Example:

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

Returns the list of paths that have been modified.

Overwrite all values in this document with the values of obj, except for immutable properties. Behaves similarly to set(), except for it unsets all properties that aren't in obj.

If this document is a subdocument or populated document, returns the document's parent. Returns the original document if there is no parent.

Populates paths on an existing document.

Example:

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

Gets _id(s) used during population of the given path.

Example:

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

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

If the path was not populated, returns undefined.

Sends a replaceOne command with this document _id as the query selector.

Valid options:

• same as in Model.replaceOne

Saves this document by inserting a new document into the database if document.isNew is true, or sends an updateOne operation only with the modifications to the database, it does not replace the whole document in the latter case.

Example:

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

If save is successful, the returned promise will fulfill with the document saved.

Example:

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

The document's schema.

Sets the value of a path, or many paths. Alias for .$set.

Example:

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

The return value of this method is used in calls to JSON.stringify(doc).

This method accepts the same options as Document#toObject. To apply the options to every document of your schema by default, set your schemas toJSON option to the same argument.

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

There is one difference between toJSON() and toObject() options. When you call toJSON(), the flattenMaps option defaults to true, because JSON.stringify() doesn't convert maps to objects by default. When you call toObject(), the flattenMaps option is false by default.

See schema options for more information on setting toJSON option defaults.

Converts this document into a plain-old JavaScript object (POJO).

Buffers are converted to instances of mongodb.Binary for proper storage.

Getters/Virtuals

Example of only applying path getters

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

Example of only applying virtual getters

doc.toObject({ virtuals: true })

Example of applying both path and virtual getters

doc.toObject({ getters: true })

To apply these options to every document of your schema by default, set your schemas toObject option to the same argument.

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

Transform:

We may need to perform a transformation of the resulting object based on some criteria, say to remove some sensitive information or return a custom object. In this case we set the optional transform function.

Transform functions receive three arguments

function (doc, ret, options) {}

• doc The mongoose document which is being converted
• ret The plain object representation which has been converted
• options The options in use (either schema options or the options passed inline)

Example:

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

With transformations we can do a lot more than remove properties. We can even return completely new customized objects:

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' }

Note: if a transform function returns undefined, the return value will be ignored.

Transformations may also be applied inline, overridding any transform set in the schema options. Any transform function specified in toObject options also propagates to any subdocuments.

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

If you want to skip transformations, use 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' }

If you pass a transform in toObject() options, Mongoose will apply the transform to subdocuments in addition to the top-level document. Similarly, transform: false skips transforms for all subdocuments. Note that this behavior is different for transforms defined in the schema: if you define a transform in schema.options.toObject.transform, that transform will not apply to subdocuments.

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

Transforms, like all of these options, are also available for toJSON. See this guide to JSON.stringify() to learn why toJSON() and toObject() are separate functions.

See schema options for some more details.

During save, no custom options are applied to the document before being sent to the database.

Helper for console.log

Clears the modified state on the specified path.

Example:

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

Sends an updateOne command with this document _id as the query selector.

Example:

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

Valid options:

• same as in Model.updateOne

Executes registered validation rules for this document.

Note:

This method is called pre save and if a validation rule is violated, save is aborted and the error is thrown.

Example:

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

Executes registered validation rules (skipping asynchronous validators) for this document.

Note:

This method is useful if you need synchronous validation.

Example:

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