MongoDB $setField Operator

What You’ll Learn

The $setField operator returns a new object with a named field set to a value you specify. The field name can be dynamic — ideal for flexible schemas, metric maps, and fields with special characters.

Definition and Usage

In MongoDB’s aggregation framework, the $setField operator takes an object, sets one field to a new value, and returns the updated object. If the field already exists, its value is replaced. If it does not exist, the field is added. The original input object is not modified unless you assign the result back to a field.

This is the write counterpart to $getField. Use it when field names come from document data — like updating whichever metric key is stored in metricKey — or when field names contain dots or $ characters that dot notation cannot handle cleanly.

📝 Syntax

The $setField operator takes an object with field, input, and value:

{
  $setField: {
    field: <string expression>,
    input: <object expression>,
    value: <expression>
  }
}

Common Patterns

// Set a static field on nested object
{ field: "status", input: "$config", value: "active" }

// Set a dynamic field from document data
{ field: "$metricKey", input: "$metrics", value: 100 }

// Add field with special characters in name
{ field: "a.b", input: "$data", value: "ok" }

Syntax Rules

• field — the name of the field to set (literal or expression).
• input — the source object to copy and modify.
• value — the new value for that field (any type).
• Returns a new object with the field added or updated.
• Returns null if input is null.
• Use inside $project, $addFields, or $set (MongoDB 5.0+).

Examples Gallery

Update nested config objects, set dynamic metric keys, handle special field names, and combine read-modify-write with $getField.

[
  {
    "_id": 1,
    "name": "Dashboard",
    "config": { "theme": "dark", "version": 2 },
    "metrics": { "views": 100, "clicks": 40 },
    "metricKey": "views"
  },
  {
    "_id": 2,
    "name": "API",
    "config": { "theme": "light" },
    "metrics": { "requests": 5000 },
    "metricKey": "requests"
  }
]

db.apps.aggregate([
  {
    $project: {
      name: 1,
      config: {
        $setField: {
          field: "status",
          input: "$config",
          value: "active"
        }
      }
    }
  }
])

// Dashboard config:
// { theme: "dark", version: 2, status: "active" }
// API config:
// { theme: "light", status: "active" }

db.apps.aggregate([
  {
    $project: {
      name: 1,
      metrics: {
        $setField: {
          field: "$metricKey",
          input: "$metrics",
          value: {
            $add: [
              {
                $getField: {
                  field: "$metricKey",
                  input: "$metrics"
                }
              },
              1
            ]
          }
        }
      }
    }
  }
])

// metricKey: "views" → metrics.views increases by 1

db.apps.aggregate([
  {
    $addFields: {
      config: {
        $setField: {
          field: "lastChecked",
          input: "$config",
          value: "$$NOW"
        }
      }
    }
  }
])

db.records.aggregate([
  {
    $project: {
      data: {
        $setField: {
          field: "user.name",
          input: "$data",
          value: "Alice"
        }
      }
    }
  }
])

// Creates field "user.name" (not nested user → name)

db.apps.updateOne(
  { _id: 1 },
  [
    {
      $set: {
        metrics: {
          $setField: {
            field: "views",
            input: "$metrics",
            value: 200
          }
        }
      }
    }
  ]
)

🚀 Use Cases

• Dynamic schemas — update whichever key a document points to (metrics, preferences, flags).
• Nested config — add or change fields on embedded configuration objects.
• Special field names — set fields containing dots or $ prefixes.
• Update pipelines — compute new nested objects during server-side updates.

💡 Best Practices