Upserting Documents with Mongoose

Upserting is a common database operation that combines updating an existing document with inserting a new one if it doesn’t exist. This is incredibly useful for scenarios where you want to ensure a record exists without knowing beforehand whether it’s already present in the database. This tutorial will guide you through the various methods of performing upserts in Mongoose, the official MongoDB object modeling tool for Node.js.

Understanding the Need for Upserts

Consider a scenario where you’re managing user profiles. You receive data from a client to update a user’s status. You want to update the user if they exist, but if they don’t, you want to create a new user record. Without upserts, you’d need to first check if the user exists, then either update or insert accordingly. This requires two database operations. Upserts streamline this process into a single operation, improving performance and reducing complexity.

Modern Approach: `updateOne()` and `findOneAndUpdate()`

The recommended approach for upserts in modern Mongoose involves using Model.updateOne() or Model.findOneAndUpdate(). These methods are built on top of MongoDB’s native update operators and provide a clean and efficient way to perform upserts.

Model.updateOne(): This method updates a single document matching a given filter. If no document matches, it inserts a new document based on the update data. It doesn’t return the updated document itself.

// Assuming 'Contact' is your Mongoose model
async function updateContactStatus(phoneNumber, newStatus) {
  try {
    const result = await Contact.updateOne(
      { phone: phoneNumber }, // Filter: Find the document with this phone number
      { $set: { status: newStatus } }, // Update: Set the status to the new value
      { upsert: true } // Upsert: Create if it doesn't exist
    );

    console.log('Update result:', result); // { acknowledged: true, matchedCount: 1, modifiedCount: 1, upsertedId: ObjectId }
  } catch (error) {
    console.error('Error updating contact:', error);
  }
}

// Example usage:
updateContactStatus('555-123-4567', 'active');

In this example, upsert: true instructs Mongoose to create a new document if no document with the specified phone number exists. The $set operator is used to update only the status field, leaving other fields untouched. The result object will indicate whether a document was matched, modified, or upserted.

Model.findOneAndUpdate(): This method is similar to updateOne(), but it returns the modified document. This is useful if you need to access the updated data immediately.

async function updateContactStatusAndGet(phoneNumber, newStatus) {
  try {
    const doc = await Contact.findOneAndUpdate(
      { phone: phoneNumber }, // Filter
      { $set: { status: newStatus } }, // Update
      { upsert: true, useFindAndModify: false, new: true } // Options
    );

    console.log('Updated document:', doc);
  } catch (error) {
    console.error('Error updating contact:', error);
  }
}

// Example usage:
updateContactStatusAndGet('555-123-4567', 'inactive');

Here, useFindAndModify: false is required as of Mongoose 6. It’s a security measure to prevent potential issues with the findAndModify function in MongoDB. The new: true option ensures that the returned document is the modified document, rather than the original.

Key Considerations

Filter and Update: The first argument to both updateOne() and findOneAndUpdate() is the filter, which specifies the criteria for finding the document. The second argument is the update, which defines the changes to be applied. Always use update operators like $set, $inc, $push, etc. to modify the document safely and predictably.
useFindAndModify: false: Remember to include this option in your findOneAndUpdate() calls when using Mongoose 6 or later.
Uniqueness: The field used in your filter (e.g., phone in the examples) should ideally have a unique index in your MongoDB collection. This ensures that you’re only ever updating a single document.

Older Approaches (Less Recommended)

While the above methods are recommended, you might encounter older code using different techniques.

Model.update() with an object as the second parameter: This approach can lead to unexpected behavior, especially with timestamps, and is generally discouraged.
findOrCreate patterns: Implementing a findOrCreate pattern manually can be complex and less efficient than using the built-in updateOne() or findOneAndUpdate().

Best Practices

Use Update Operators: Always use MongoDB update operators (e.g., $set, $inc) to modify documents. This ensures data consistency and prevents accidental overwrites.
Validate Data: Before performing an upsert, validate the data to ensure it meets your requirements.
Handle Errors: Always handle potential errors during the upsert operation to prevent unexpected behavior.

By following these guidelines, you can efficiently and reliably upsert documents in Mongoose, ensuring data consistency and streamlining your application logic.