Predefined Update Options Quick Reference

Arrays

$push

Adds an element to the end of an array. If the field is not an array yet, a new array with the element is created.

{
    $push: { tags: "designer" }
}

Input:

{
    tags: ["developer"]
}

Output:

{
    tags: ["developer", "designer"]
}

$pushSet

Adds an element to the end of an array and removes duplicates.

{
    $pushSet: { tags: "designer" }
}

Input:

{
    tags: ["developer", "designer", "developer"]
}

Output:

{
    tags: ["developer", "designer"]
}

$pull

Removes a specific element from an array.

{
    $pull: { tags: "developer" }
}

Input:

{
    tags: ["developer", "designer"]
}

Output:

{
    tags: ["designer"]
}

$pullAll

Removes all occurrences of specified elements from an array.

{
    $pullAll: { tags: ["developer", "designer"] }
}

Input:

{
    tags: ["developer", "designer", "manager"]
}

Output:

{
    tags: ["manager"]
}

$pushAll

Adds multiple elements to the end of an array.

{
    $pushAll: { tags: ["developer", "designer"] }
}

Input:

{
    tags: ["manager"]
}

Output:

{
    tags: ["manager", "developer", "designer"]
}

Numbers

$inc

Increments a numeric value by a given amount.

{
    $inc: { counter: 1 }
}

Input:

{
    counter: 5
}

Output:

{
    counter: 6
}

$dec

Decrements a numeric value by a given amount.

{
    $dec: { counter: 1 }
}

Input:

{
    counter: 5
}

Output:

{
    counter: 4
}

Objects

$merge

Merges a nested object, adding or updating properties. For arrays, concatenates them.

{
    $merge: { 
        settings: {
            theme: "dark",
            roles: ["admin"]
        }
    }
}

Input:

{
    settings: {
        theme: "light",
        language: "en",
        roles: ["user"]
    }
}

Output:

{
    settings: {
        theme: "dark",
        language: "en",
        roles: ["user", "admin"]
    }
}

$deepMerge

Deeply merges nested objects, adding or updating properties recursively.

{
    $deepMerge: {
        user: {
            address: {
                city: "New York"
            }
        }
    }
}

Input:

{
    user: {
        name: "John",
        address: {
            street: "123 Main St",
            city: "San Francisco"
        }
    }
}

Output:

{
    user: {
        name: "John",
        address: {
            street: "123 Main St",
            city: "New York"
        }
    }
}

Others

$set

Sets a field to a specific value. Functionally identical to using a plain field assignment in the updater object.

{
    $set: { name: "John" }
}

Input:

{
    name: "Jane",
    age: 30
}

Output:

{
    name: "John",
    age: 30
}

Note: { $set: { name: "John" } } is equivalent to { name: "John" }.

$unset

Removes a specified key from an object.

{
    $unset: { age: true }
}

Input:

{
    name: "John",
    age: 30
}

Output:

{
    name: "John"
}

$rename

Renames a key in an object.

{
    $rename: { firstName: "name" }
}

Input:

{
    firstName: "John",
    lastName: "Doe"
}

Output:

{
    name: "John",
    lastName: "Doe"
}

Function-Based Updater

Deprecated: function-based updaters will be removed in a future release. Use operator objects, or compute the new document in application code and pass it as data.

Instead of using operator objects, you can provide a function for fully custom update logic:

// Updater function signature:
(data: T, context: VContext) => Data | void

The function receives the current document and a context object. It works in one of two modes:

1. Mutate in place and return void - the mutated document is stored (safe way to change a few fields):

// Example: double the counter field
await db.users.updateOne(
  { name: "Alice" },
  user => { user.counter = user.counter * 2; }
);

// Example: using context for external values
await db.users.update(
  { status: "active" },
  (user, ctx) => { user.score = user.score + ctx.bonus; },
  { bonus: 10 },  // context
);

1. Return a new object - the returned object replaces the whole document. It is not merged with the original:

// Returns a full replacement document
await db.users.updateOne(
  { name: "Alice" },
  user => ({ ...user, counter: user.counter * 2 })
);

Warning: returning a partial object replaces the document entirely:

// WRONG: the document becomes { counter: 4 } and loses all other fields
await db.users.updateOne(
  { name: "Alice" },
  user => ({ counter: user.counter * 2 })
);

Note: for partial field updates, prefer mutation, plain field assignment ({ counter: 5 }), or operators like $inc and $set.