What Is the __v Field in Mongoose

Mongoose is a high-level ODM (Object Data Modeling) library for Node.js and MongoDB. If you’re using Mongoose, you may notice that a field named __v has been automatically added to your documents. In this article, we are going to explain, what is __v field, its usage, how it interacts with Mongoose, and how you can suppress or control it when needed.

• What is  __v Field?
  • Purpose of the __v Field
• How Mongoose Uses the __v Field
  • Example of __v
• Managing the __v Field
  • Removing the __v Field
  • Keeping __v While Hiding It in API Responses
• Conclusion
• FAQs
  • Can I rename the __v field?
  • Will the __v field be added to all collections?
  • Is the __v field updated during direct updates via updateOne or updateMany?
  • How do I use the __v field for optimistic concurrency?
  • Does disabling __v affect performance?

What is  __v Field?

The __v field is a version key added by Mongoose to documents in MongoDB. A version key in MongoDB added by Mongoose as __v is used to track the version of a document. It is automatically included unless explicitly disabled.

Purpose of the __v Field

The purpose of the __v field is to track the version of a document which prevents conflicts when multiple users try to update the same document at the same time.

For instance:

• The __v value in the database must match the version of the document being currently updated in Mongoose. If the versions do not match, it indicates a conflict preventing accidental overwrites.

How Mongoose Uses the __v Field

The __v field is automatically incremented in Mongoose when a document is updated using the save method.

Example of __v

Let’s take a simple schema and a saved document:

Initial Document:

const user = new User({ name: 'aman', email: '[email protected]' });

await user.save();

This creates a document with:

{
  "_id": "your_id",
  "name": "aman",
  "email": "[email protected]",
  "__v": 0
}

First Update:

const user1 = await User.findById("your_id");
user1.name = icon;
await user1.save(); // The version key (__v) is incremented

The document is now:

{
  "_id": "your_id",
  "name": "icon",
  "email": "[email protected]",
  "__v": 1
}

Second Update with Conflicting Version:

const user2 = await User.findById("your_id");
user2.email = ‘[email protected]';
user2.__v = 0;

#Here, user2 is manually setting the version key to 0, as if it’s an older version

await user2.save();

Saving this will trigger an error, because the version value doesn’t match.

In this case, an error will occur because the __v field doesn’t match the current version of the document (1), preventing the accidental overwriting of changes.

This example shows how the __v field helps to manage updates and prevents conflicts when multiple users try to update the same document.

Managing the __v Field

Removing the __v Field

If you don’t need versioning, you can disable the __v field by setting the versionKey option to false in your schema definition::

const schema = new mongoose.Schema({ name: String }, { versionKey: false });

This will prevent Mongoose from adding the __v field to your documents.

Keeping __v While Hiding It in API Responses

You may wish to retain the __v field for certain internal purposes, but not want it to appear in API responses. This can be done using the toJSON or toObject transform options:

const schema = new mongoose.Schema({ name: String });
schema.set('toJSON', {
  transform: (doc, ret) => {
    delete ret.__v;
    return ret;
  },
});

Now, the __v field will not appear in JSON outputs but will still exist in the database.

Conclusion

The __v field in Mongoose is a version key to keep track of the updates on a document and thus handle optimistic concurrency. It can be disabled or hidden if not needed for an application. Knowledge of how to handle the __v field would help you gain better control over your data and application behavior. If you want to learn these specifics of Web Development, then you should head to our Full Stack Developer Course.

FAQs

const schema = new mongoose.Schema({ name: String }, { versionKey: 'version' });

const schema = new mongoose.Schema({ name: String }, { optimisticConcurrency: true });