diff --git a/README.md b/README.md index eb5b394..e233ada 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,7 @@ db.find({ $or: [{ planet: 'Earth' }, { planet: 'Mars' }], inhabited: true }, fun * `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 available modifiers are `$set` to change a field's value and `$inc` to increment a field's value. The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs. See examples below for the syntax + * The available modifiers are `$set` to change a field's value, `$inc` to increment a field's value and `$push`, `$pop`, `$addToSet` to work on arrays. The modifiers create the fields they need to modify if they don't exist, and you can apply them to subdocs. 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 @@ -259,6 +259,27 @@ db.update({ planet: 'Pluton' }, { planet: 'Pluton', inhabited: false }, { upsert db.update({ planet: 'Pluton' }, { $inc: { distance: 38 } }, { upsert: true }, function () { // A new document { _id: 'id5', planet: 'Pluton', distance: 38 } has been added to the collection }); + +// If we insert a new document { _id: 'id6', fruits: ['apple', 'orange', 'pear'] } in the collection, +// let's see how we can modify the array field atomically + +// $push inserts new elements at the end of the array +db.update({ _id: 'id6' }, { $push: { fruits: ['banana'] } }, {}, function () { + // Now the fruits array is ['apple', 'orange', 'pear', 'banana'] +}); + +// $pop removes an element from the end (if used with 1) or the front (if used with -1) of the array +db.update({ _id: 'id6' }, { $pop: { fruits: 1 } }, {}, function () { + // Now the fruits array is ['apple', 'orange'] + // With { $pop: { fruits: -1 } }, it would have been ['orange', 'pear'] +}); + +// $addToSet adds an element to an array only if it isn't already in it +// Note that it doesn't check whether the array contained duplicates before or not +db.update({ _id: 'id6' }, { $addToSet: { fruits: ['apple'] } }, {}, function () { + // The fruits array didn't change + // If we had used a fruit not in the array, e.g. 'banana', it would have been added to the array +}); ``` ### Removing documents