Fork me on GitHub


Mongoose documents represent a one-to-one mapping to documents as stored in MongoDB. Each document is an instance of its Model.


There are many ways to retrieve documents from MongoDB. We won't cover that in this section. See the chapter on querying for detail.


There are a number of ways to update documents. We'll first look at a traditional approach using findById:

Tank.findById(id, function (err, tank) {
  if (err) return handleError(err);
  tank.size = 'large'; (err, updatedTank) {
    if (err) return handleError(err);

This approach involves first retrieving the document from Mongo, then issuing an update command (triggered by calling save). However, if we don't need the document returned in our application and merely want to update a property in the database directly, Model#update is right for us:

Tank.update({ _id: id }, { $set: { size: 'large' }}, callback);

If we do need the document returned in our application there is another, often better, option:

Tank.findByIdAndUpdate(id, { $set: { size: 'large' }}, { new: true }, function (err, tank) {
  if (err) return handleError(err);

The findAndUpdate/Remove static methods all make a change to at most one document, and return it with just one call to the database. There are several variations on the findAndModify theme. Read the API docs for more detail.

_Note that findAndUpdate/Remove do not execute any hooks or validation before making the change in the database. You can use the runValidators option to access a limited subset of document validation. However, if you need hooks and full document validation, first query for the document and then save() it._


Documents are validated before they are saved. Read the api docs or the validation chapter for detail.

Next Up

Now that we've covered Documents, let's take a look at Sub-documents.