Add more info to docs for update() function

[clintharris]

Please add something like the following to the documentation (here and here) 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) that you can use it to insert/replace entire documents. Example:

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{...});

[mlegenhausen]

+1
I had exactly all the problems you described here...

[diogogmt]

+1

[mgodwin]

+1 - Especially mentioning 'upsert' in the actual documentation would be great!

[saifbechan]

+1 Same problem here. Removing _id from the object did the trick for me. This should be added to the docs.

[aheckmann]

we'll be rewritting the docs soon.

[dopa]

+1 - has this been updated?

[aheckmann]

not yet. v3 alpha is almost out. will start docs afterward

[sandinmyjoints]

+1

[agoole]

V3 is out and I saw that this issue is still open. I'm having issues with update and upsert not using the default values when creating a document when one isn't found. Docs would really help.

[aheckmann]

The docs were updated in v3. Anyone want to submit a pull request for this? Should be pretty easy.

[LiamKarlMitchell]

Can we do this in .save if there is an option like update:true.

[LiorZ]

+1

[enricleon]

+1

[d0nd3r3k]

+1

[madhums]

+1

[RyanQuackenbush]

+1

[simonh1000]

This is great, except that when I try to implement it I am getting an element with _id null and that is being overwritten whenever I am creating new elements. My existing elements have an _id of type ObjectID and can thus be distinguished

[samschooler]

I'm having the same issue as simonh1000. The _id value is set to null on update.

[simonh1000]

I now use this coffeescript
id = if item._id is "" then mongoose.Types.ObjectId() else item._id and that works

[samschooler]

Alright! Thanks! I got mine working now.

[tristan625]

+1

[skoope]

Man you're a hero thank you ! +1