The $push operator in MongoDB is used to append a specified value to an array within a document. When using $push, if the field being updated is not already an array, the operation will fail. If the field does not exist, $push will add the array field with the specified value as its element. It's important to note that if the value being pushed is an array itself, $push will add the entire array as a single element unless the $each modifier is used, which allows for appending multiple values to the array field individually¹.

Syntax and Behavior

The basic syntax for $push is as follows:

To target a field within an embedded document or an array, dot notation should be used. For example, to append a score of 89 to a scores array within a students collection, the following update operation can be used:

This operation will result in the scores array containing the new value of 89¹.

Modifiers and Multiple Updates

The $push operator can be combined with modifiers such as $each, $sort, and $slice to provide more control over the update operation. For instance, to append multiple values and then sort and limit the array, the following syntax can be used:

This operation will append the new quiz scores, sort the quizzes array in descending order by score, and then limit the array to the top three scores¹.

Combining $push with Other Update Operators

MongoDB allows for combining $push with other update operators like $set and $inc in a single update operation. This is useful when you need to modify different aspects of a document simultaneously. For example, to add a new subject to a student's record and update the total marks, the following operation can be performed:

This operation will set the totalMarks to 170 and push a new subject into the subjectDetails array for the student with studentId 1023².

Practical Example

Consider a scenario where you need to update an invoice document by adding a payment entry, updating the payment status, and incrementing the total amount paid. The following MongoDB operation achieves this:

This operation will push a new payment entry into the payment array, set the payment_status to true, update the updated_at timestamp, and increment the total_amount_paid by the specified amount³.

Conclusion

The $push operator is a powerful tool for array updates in MongoDB documents. It can be used alone or in conjunction with other update operators to perform complex updates in a single operation. Understanding how to use $push effectively can help maintain data integrity and reduce the number of operations required to update documents.