Predefined Update Options Quick Reference

Arrays

$push

Adds an element to the end of an array.

{
    $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

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

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

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

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

The function receives the current document and a context object. It can either: 1. Return a new object with the fields to update 2. Mutate the document in place and return void