LearnBoost/mongoose — Issue #571: Add more info to docs for update() function
Author: clintharris
Created: 2011-10-21 21:05:25+00:00
State: open

Please add something like the following to the documentation ([here](http://mongoosejs.com/docs/api.html) and [here](http://mongoosejs.com/docs/finding-documents.html)) for the update() function:

> Be careful to not use an existing model instance for the update clause (this won't work and can cause weird behavior like infinite loops). Also, ensure that the update clause does not have an _id property, which causes Mongo to return a `"Mod on _id not allowed"` error.

The documentation currently only shows update() being used with a modifier like $inc, [but it's not immediately clear to newbies (like myself)](http://stackoverflow.com/questions/7267102/how-do-i-update-upsert-a-document-in-mongoose) that you can use it to insert/replace entire documents. Example:

```javascript
var contact = new Contact({
phone: request.phone,
status: request.status
});

// Convert the Model instance to a simple object using Model's 'toObject' function
// to prevent weirdness like infinite looping...
var upsertData = contact.toObject();

// Delete the _id property, otherwise Mongo will return a "Mod on _id not allowed" error
delete upsertData._id;

// Do the upsert, which works like this: If no Contact document exists with
// _id = contact.id, then create a new doc using upsertData.
// Otherwise, update the existing doc with upsertData
Contact.update({_id: contact.id}, upsertData, {upsert: true}, function(err{...});
```