3.1 Field Update Operators

3.1 Field Update Operators

In MongoDB, update operations modify existing documents in a collection without replacing the entire document structure. MongoDB provides field update operators that perform atomic, in-place modifications on specific fields. Understanding the mechanics of update methods, return documents, upsert behavior, and atomic field operators is essential for building scalable applications and passing the MongoDB Associate Developer Exam.

---

1. Core Update Methods

MongoDB provides two primary methods for updating documents in a collection:

• db.collection.updateOne(filter, update, options): Modifies the first document that matches the query filter according to the natural storage order or specified index sort.
• db.collection.updateMany(filter, update, options): Modifies all documents in the collection that satisfy the query filter criteria.

Syntax Structure

db.collection.updateOne(
  { status: "PENDING", priority: { $gte: 3 } }, // Query filter
  {
    $set: { status: "IN_PROGRESS", assignedAt: new Date() },
    $inc: { retryCount: 1 }
  }, // Update document containing update operators
  {
    upsert: false,
    writeConcern: { w: "majority", wtimeout: 5000 }
  } // Options document
);

Critical Exam Rule: In modern MongoDB drivers and the mongosh shell, the update argument must contain update operators (e.g., $set, $inc) or an aggregation pipeline array. Supplying raw field-value pairs (e.g., { status: "IN_PROGRESS" }) without an update operator will throw a runtime error in updateOne() and updateMany().

---

2. Update Result & Return Objects

When updateOne() or updateMany() executes, MongoDB returns an acknowledgment document detailing the exact outcome of the operation:

{
  acknowledged: true,
  matchedCount: 5,
  modifiedCount: 3,
  upsertedId: null,
  upsertedCount: 0
}

Anatomy of the Return Document

matchedCount vs. modifiedCount Discrepancy

Consider a collection with a document: { _id: 1, status: "active", tier: "gold" }.

db.users.updateOne(
  { _id: 1 },
  { $set: { status: "active" } }
);

Result:

{
  acknowledged: true,
  matchedCount: 1,
  modifiedCount: 0,
  upsertedId: null,
  upsertedCount: 0
}

Because the value of status was already "active", MongoDB detects that no byte-level changes are required. The document matched the query filter (matchedCount: 1), but the document was not altered (modifiedCount: 0). WiredTiger avoids unnecessary disk writes and oplog generation in this scenario.

---

3. Upsert Mechanics (upsert: true)

An upsert is a hybrid operation: if a document matching the query filter exists, MongoDB applies the update; if no matching document exists, MongoDB inserts a new document.

db.analytics.updateOne(
  { page: "/checkout", date: "2026-09-02" }, // Filter
  {
    $inc: { views: 1 },
    $set: { lastAccessed: new Date() },
    $setOnInsert: { createdAt: new Date(), initialReferrer: "direct" }
  },
  { upsert: true } // Options
);

How MongoDB Constructs an Upserted Document

When upsert: true is triggered and no document matches the filter, MongoDB constructs the new document through the following process:

1. Extracts Equality Clauses from the Filter: All top-level field equality conditions in the filter become initial fields in the new document (e.g., page: "/checkout", date: "2026-09-02").
2. Applies Update Operator Modifications: Fields specified in operators like $set, $inc, and $currentDate are evaluated and added.
3. Evaluates $setOnInsert: Fields defined inside $setOnInsert are populated only upon insertion. If a matching document had been found, $setOnInsert directives would be completely ignored.
4. Generates _id: If neither the query filter nor the update operators supply an _id, MongoDB generates a new ObjectId.

---

4. Comprehensive Field Update Operators

MongoDB provides specialized field operators to manipulate values atomically within documents.

The Field Operators Matrix

---

5. In-Depth Operator Analysis & Code Examples

5.1 $set and Dot Notation for Embedded Fields

$set replaces the value of a field with the specified value. It supports dot notation to reach deeply nested fields without overwriting adjacent sibling properties.

db.users.updateOne(
  { _id: 1001 },
  {
    $set: {
      "profile.contact.email": "alex.dev@example.com",
      "preferences.notifications.sms": false,
      "accountStatus": "VERIFIED"
    }
  }
);

If profile.contact exists, only email is updated. If profile or contact does not exist, MongoDB creates the intermediate embedded subdocuments automatically.

5.2 $unset Field Deletion

$unset removes specified fields from documents. The value specified in the $unset expression (such as "" or 1) is ignored by MongoDB.

db.products.updateMany(
  { discontinued: true },
  {
    $unset: {
      temporaryPromoCode: "",
      flashSaleDiscount: 1
    }
  }
);

5.3 $inc and $mul for Mathematical Operations

$inc accepts positive numbers (to increment) or negative numbers (to decrement), including integers, longs, doubles, and Decimal128 values.

db.inventory.updateOne(
  { sku: "MDB-BOOK-01" },
  {
    $inc: { quantity: -5, reservedCount: 5 },
    $mul: { price: 1.10 } // 10% price increase
  }
);

Exam Trap: $inc and $mul can only be applied to fields containing numeric types. Applying $inc to a string or null field will throw a Cannot apply $inc to a value of non-numeric type error.

5.4 $min and $max for Threshold Tracking

$min updates a field if the given value is smaller than the current field value. $max updates a field if the given value is greater than the current field value.

db.gameScores.updateOne(
  { playerId: "player_88" },
  {
    $max: { highScore: 9450 },       // Updated only if 9450 > current highScore
    $min: { bestLapTimeSec: 42.18 }, // Updated only if 42.18 < current bestLapTimeSec
    $currentDate: { lastPlayed: true }
  },
  { upsert: true }
);

If playerId: "player_88" does not exist and an upsert occurs, MongoDB creates the document and sets highScore: 9450 and bestLapTimeSec: 42.18 because both $min and $max set the field when it is missing.

5.5 $rename for Atomic Key Migration

$rename alters field names within documents. It works on top-level fields as well as embedded subdocuments.

db.customers.updateMany(
  {},
  {
    $rename: {
      "cell": "mobileNumber",
      "billing.zip": "billing.postalCode"
    }
  }
);

Key $rename Constraints:

1. If the document already contains a field with <new_name>, $rename removes the existing field and assigns the value from <old_name>.
2. $rename cannot move fields into or out of array elements.

5.6 $currentDate Type Options

$currentDate sets fields to the server's current date/time. It supports two representations:

1. BSON Date (Default): Specified as { field: true } or { field: { $type: "date" } }.
2. BSON Timestamp: Specified as { field: { $type: "timestamp" } } (used internally in oplogs and replication).

db.sessions.updateOne(
  { sessionId: "sess_abc123" },
  {
    $currentDate: {
      lastActivity: true,                     // BSON Date
      clusterSyncTime: { $type: "timestamp" } // BSON Timestamp
    }
  }
);