what is the difference between document middleware, model middleware, aggregate middleware, and query middleware?

Question

I am fairly new to MongoDB and Mongoose, I am really confused about why some of the middleware works at the document and some works on query. I am also confused about why some of the query methods return documents and some return queries. If a query is returning document it is acceptable, but why a query return query and what really it is.

Adding more to my question what is a Document function and Model or Query function, because both of them have some common methods like updateOne.

Moreover, I have gathered all these doubts from the mongoose documentation.

Answer 1

Tl;dr: the type of middleware most commonly defines what the this variable in a pre/post hook refers to:

Middleware Hook	'this' refers to the	methods
Document	Document	validate, save, remove, updateOne, deleteOne, init
Query	Query	count, countDocuments, deleteMany, deleteOne, estimatedDocumentCount, find, findOne, findOneAndDelete, findOneAndRemove, findOneAndReplace, findOneAndUpdate, remove, replaceOne, update, updateOne, updateMany
Aggregation	Aggregation object	aggregate
Model	Model	insertMany

Long explanation:

Middlewares are nothing, but built-in methods to interact with the database in different ways. However, as there are different ways to interact with the database, each with different advantages or preferred use-cases, they also behave differently to each other and therefor their middlewares can behave differently, even if they have the same name.

By themselves, middlewares are just shorthands/wrappers for the mongodbs native driver that's being used under the hood of mongoose. Therefor, you can usually use all middlewares, as if you were using regular methods of objects without having to care if it's a Model-, Query-, Aggregation- or Document-Middleware, as long as it does what you want it to.

However, there are a couple of use-cases where it is important to differentiate the context in which these methods are being called.

The most prominent use-case being hooks. Namely the *.pre() and the *.post() hooks. These hooks are methods that you can "inject" into your mongoose setup, so that they are being executed before or after specific events.

For example: Let's assume I have the following Schema:

const productSchema = new Schema({
  name: 'String',
  version: {
    type: 'Number',
    default: 0
  }
});

Now, let's say you always want to increase the version field with every save, so that it automatically increases the version field by 1.

The easiest way to do this would be to define a hook that takes care of this for us, so we don't have to care about this when saving an object. If we for example use .save() on the document we just created or fetched from the database, we'd just have to add the following pre-hook to the schema like this:

 productSchema.pre('save', function(next) {
   this.version = this.version + 1; // or this.version += 1;
   next();
 });

Now, whenever we call .save() on a document of this schema/model, it will always increment the version before it is actually being saved, even if we only changed the name.

However, what if we don't use the .save() or any other document-only middleware but e.g. a query middleware like findOneAndUpdate() to update an object?

Then, we won't be able to use the pre('save') hook, as .save() won't be called. In this case, we'd have to implement a similar hook for findOneAndUpdate().

Here, however, we finally come to the differences in the middlewares, as the findOneAndUpdate() hook won't allow us to do that, as it is query hook, meaning it does not have access to the actual document, but only to the query itself. So if we e.g. only change the name of the product the following middleware would not work as expected:

 productSchema.pre('findOneAndUpdate', function(next) {
   // this.version is undefined in the query and would therefor be NaN
   this.version = this.version + 1;
   next();
 });

The reason for this is, that the object is directly updated in the database and not first "downloaded" to nodejs, edited and "uploaded" again. This means, that in this hook this refers to the query and not the document, meaning, we don't know what the current state of version is. If we were to increment the version in a query like this, we'd need to update the hook as follows, so that it automatically adds the $inc operator:

 productSchema.pre('findOneAndUpdate', function(next) {
   this.$inc =  { version: 1 };
   next();
 });

Alternatively, we could emulate the previous logic by manually fetching the target document and editing it using an async function. This would be less efficient in this case, as it would always call the db twice for every update, but would keep the logic consistent:

productSchema.pre('findOneAndUpdate', async function() {
  const productToUpdate = await this.model.findOne(this.getQuery());
  this.version = productToUpdate.version + 1;
  next();
});

For a more detailed explanation, please the check the official documentation that also has a designated paragraph for the problem of having colliding naming of methods (e.g. remove() being both a Document and Query middleware method)