Updating documents

db.update(query, update, options, callback) will update all documents matching query according to the update rules:

  • query is the same kind of finding query you use with find and findOne
  • update specifies how the documents should be modified. It is either a new document or a set of modifiers (you cannot use both together, it doesn't make sense!)
    • A new document will replace the matched docs
    • The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs. Available field modifiers are $set to change a field's value, $unset to delete a field, $inc to increment a field's value and $min/$max to change field's value, only if provided value is less/greater than current value. To work on arrays, you have $push, $pop, $addToSet, $pull, and the special $each and $slice. See examples below for the syntax.
  • options is an object with two possible parameters
    • multi (defaults to false) which allows the modification of several documents if set to true
    • upsert (defaults to false) if you want to insert a new document corresponding to the update rules if your query doesn't match anything. If your update is a simple object with no modifiers, it is the inserted document. In the other case, the query is stripped from all operator recursively, and the update is applied to it.
    • returnUpdatedDocs (defaults to false, not MongoDB-compatible) if set to true and update is not an upsert, will return the array of documents matched by the find query and updated. Updated documents will be returned even if the update did not actually modify them.
  • callback (optional) signature: (err, numAffected, affectedDocuments, upsert). Warning: the API was changed between v1.7.4 and v1.8. Please refer to the change log to see the change.
    • For an upsert, affectedDocuments contains the inserted document and the upsert flag is set to true.
    • For a standard update with returnUpdatedDocs flag set to false, affectedDocuments is not set.
    • For a standard update with returnUpdatedDocs flag set to true and multi to false, affectedDocuments is the updated document.
    • For a standard update with returnUpdatedDocs flag set to true and multi to true, affectedDocuments is the array of updated documents.

Note: you can't change a document's _id.

  1. // Let's use the same example collection as in the "finding document" part
  2. // { _id: 'id1', planet: 'Mars', system: 'solar', inhabited: false }
  3. // { _id: 'id2', planet: 'Earth', system: 'solar', inhabited: true }
  4. // { _id: 'id3', planet: 'Jupiter', system: 'solar', inhabited: false }
  5. // { _id: 'id4', planet: 'Omicron Persia 8', system: 'futurama', inhabited: true }
  7. // Replace a document by another
  8. db.update({ planet: 'Jupiter' }, { planet: 'Pluton'}, {}, function (err, numReplaced) {
  9.   // numReplaced = 1
  10.   // The doc #3 has been replaced by { _id: 'id3', planet: 'Pluton' }
  11.   // Note that the _id is kept unchanged, and the document has been replaced
  12.   // (the 'system' and inhabited fields are not here anymore)
  13. });
  15. // Set an existing field's value
  16. db.update({ system: 'solar' }, { $set: { system: 'solar system' } }, { multi: true }, function (err, numReplaced) {
  17.   // numReplaced = 3
  18.   // Field 'system' on Mars, Earth, Jupiter now has value 'solar system'
  19. });
  21. // Setting the value of a non-existing field in a subdocument by using the dot-notation
  22. db.update({ planet: 'Mars' }, { $set: { "data.satellites": 2, "data.red": true } }, {}, function () {
  23.   // Mars document now is { _id: 'id1', system: 'solar', inhabited: false
  24.   //                      , data: { satellites: 2, red: true }
  25.   //                      }
  26.   // Not that to set fields in subdocuments, you HAVE to use dot-notation
  27.   // Using object-notation will just replace the top-level field
  28.   db.update({ planet: 'Mars' }, { $set: { data: { satellites: 3 } } }, {}, function () {
  29.     // Mars document now is { _id: 'id1', system: 'solar', inhabited: false
  30.     //                      , data: { satellites: 3 }
  31.     //                      }
  32.     // You lost the "data.red" field which is probably not the intended behavior
  33.   });
  34. });
  36. // Deleting a field
  37. db.update({ planet: 'Mars' }, { $unset: { planet: true } }, {}, function () {
  38.   // Now the document for Mars doesn't contain the planet field
  39.   // You can unset nested fields with the dot notation of course
  40. });
  42. // Upserting a document
  43. db.update({ planet: 'Pluton' }, { planet: 'Pluton', inhabited: false }, { upsert: true }, function (err, numReplaced, upsert) {
  44.   // numReplaced = 1, upsert = { _id: 'id5', planet: 'Pluton', inhabited: false }
  45.   // A new document { _id: 'id5', planet: 'Pluton', inhabited: false } has been added to the collection
  46. });
  48. // If you upsert with a modifier, the upserted doc is the query modified by the modifier
  49. // This is simpler than it sounds :)
  50. db.update({ planet: 'Pluton' }, { $inc: { distance: 38 } }, { upsert: true }, function () {
  51.   // A new document { _id: 'id5', planet: 'Pluton', distance: 38 } has been added to the collection  
  52. });
  54. // If we insert a new document { _id: 'id6', fruits: ['apple', 'orange', 'pear'] } in the collection,
  55. // let's see how we can modify the array field atomically
  57. // $push inserts new elements at the end of the array
  58. db.update({ _id: 'id6' }, { $push: { fruits: 'banana' } }, {}, function () {
  59.   // Now the fruits array is ['apple', 'orange', 'pear', 'banana']
  60. });
  62. // $pop removes an element from the end (if used with 1) or the front (if used with -1) of the array
  63. db.update({ _id: 'id6' }, { $pop: { fruits: 1 } }, {}, function () {
  64.   // Now the fruits array is ['apple', 'orange']
  65.   // With { $pop: { fruits: -1 } }, it would have been ['orange', 'pear']
  66. });
  68. // $addToSet adds an element to an array only if it isn't already in it
  69. // Equality is deep-checked (i.e. $addToSet will not insert an object in an array already containing the same object)
  70. // Note that it doesn't check whether the array contained duplicates before or not
  71. db.update({ _id: 'id6' }, { $addToSet: { fruits: 'apple' } }, {}, function () {
  72.   // The fruits array didn't change
  73.   // If we had used a fruit not in the array, e.g. 'banana', it would have been added to the array
  74. });
  76. // $pull removes all values matching a value or even any NeDB query from the array
  77. db.update({ _id: 'id6' }, { $pull: { fruits: 'apple' } }, {}, function () {
  78.   // Now the fruits array is ['orange', 'pear']
  79. });
  80. db.update({ _id: 'id6' }, { $pull: { fruits: $in: ['apple', 'pear'] } }, {}, function () {
  81.   // Now the fruits array is ['orange']
  82. });
  84. // $each can be used to $push or $addToSet multiple values at once
  85. // This example works the same way with $addToSet
  86. db.update({ _id: 'id6' }, { $push: { fruits: { $each: ['banana', 'orange'] } } }, {}, function () {
  87.   // Now the fruits array is ['apple', 'orange', 'pear', 'banana', 'orange']
  88. });
  90. // $slice can be used in cunjunction with $push and $each to limit the size of the resulting array.
  91. // A value of 0 will update the array to an empty array. A positive value n will keep only the n first elements
  92. // A negative value -n will keep only the last n elements.
  93. // If $slice is specified but not $each, $each is set to []
  94. db.update({ _id: 'id6' }, { $push: { fruits: { $each: ['banana'], $slice: 2 } } }, {}, function () {
  95.   // Now the fruits array is ['apple', 'orange']
  96. });
  98. // $min/$max to update only if provided value is less/greater than current value
  99. // Let's say the database contains this document
  100. // doc = { _id: 'id', name: 'Name', value: 5 }
  101. db.update({ _id: 'id1' }, { $min: { value: 2 } }, {}, function () {
  102.   // The document will be updated to { _id: 'id', name: 'Name', value: 2 }
  103. });
  105. db.update({ _id: 'id1' }, { $min: { value: 8 } }, {}, function () {
  106.   // The document will not be modified
  107. });