Documents

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

Retrieving

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

Updating

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';
  tank.save(function (err) {
    if (err) return handleError(err);
    res.send(tank);
  });
});

This approach involves first retreiving 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' }}, function (err, tank) {
  if (err) return handleError(err);
  res.send(tank);
});

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. If you need hooks and validation, first query for the document and then save it.

Validating

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.