Oplog Update Version ($v) Digest

This document describes how the MongoDB oplog update version ($v) works. It will be useful to anyone who’s into trying to understand the internal parts of the MongoDB oplog format.

The MongoDB oplog is an internal part of the MongoDB replication system. It is also used for other purposes, such as creating incremental backups or replaying changes to data in order to perform point-in-time recovery.

What role does the $v field play into the oplog entries

This field was first introduced in Mongo 3.6, and it’s placed under the o field. It represents the version of the oplog format used for updates. Initially the only value of this field was 1, and nothing else changed. It kept defining the operations in terms of $set/$unset.

{
    "op": "u",
    "ns": "db.collection",
    "o": {
        "$v": 1,
        "$set": {
            "foo": "bar"
        }
    },
    "o2": {
        "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "v": 2
}

In Mongo 4.6, the $v field started using the value 2. It resulted in a change in the format used to represent the operations. A new diff field was added. This field is a recursive structure made of the following optional fields:

u: Top level update (old $set)
d: Top level unset (old $unset)
i: Nested field update. (old $set of the nested field)
s-fields (fields starting by s) they can either be:
- array operations; or
- nested field operations

{
    "op": "u",
    "ns": "db.collection",
    "o": {
        "$v": 2,
        "diff": {
            "u": {
                "foo": "bar"
            }
        }
    },
    "o2": {
        "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
    },
    "v": 2
}

Examples of $v:2 operations to $v:1 operations

// u
{ "diff": { "u": { "foo": "2", "bar": "xx" } } }
{ "$set": { "foo": "2", "bar": "xx" } }


// d
{ "diff": { "d": { "foo": false } } }
{ "$unset": { "foo": true } }


// i
{ "diff": {"i": { "foo": { "bar": 2 } } } }
{ "$set": { "foo.bar": 2 } }


// nested field s+i
{ "diff": { "sa": { "i": { "foo": 3, "bar": 1 } } } }
{ "$set": { "a.foo": 3, "a.bar": 1 } }


// nested field s+d
{ "diff": { "sa": { "d": { "foo": false } } } }
{ "$unset": { "a.foo": true } }


// array field u
{ "diff": { "sfoo": { "a": true, "u0": 2 } } }
{ "$set": { "foo.0": 2 } }


// array field d
{ "diff": { "sfoo": { "a": true, "u0": null } } }
{ "$unset": { "foo.0": true } }

References

https://jira.mongodb.org/browse/SERVER-32240
https://github.com/meteor/meteor/blob/master/packages/mongo/oplog_v2_converter.js