Update db.collection.save.txt

[normgraham]

When provided a document with an _id, save() always performs an update with upsert, never an insert. Save() only performs an insert command when the _id is missing from the specified document.

[kay-kim]

Hi Norm -- we currently have the following where the first sentence encapsulates what the save() does and the following two explain exactly what update w upsert does.

If the document contains an _id field, then the save() method performs an update with upsert, querying by the _id field. If a document does not exist with the specified _id value, the save() method performs an insert. If a document exists with the specified _id value, the save() method performs an update that replaces all fields in the existing document with the fields from the document.

If you prefer, we could be more explicit in the relationship between the sentences such as:

If the document contains an _id field, then the save() method performs an update with upsert, querying by the _id field: i.e. if a document does not exist with ... and if a document exists with the ...
-or-
With an update with upsert, if a document ... and if ...

[normgraham]

Hi Kay,

It's the "If a document does not exist with the specified _id value, the
save() method performs an insert" that I was trying to work with. Yes, the
document is inserted into the collection, but operation you'll find in the
system.profile collection and in the mongodb logs is an "update". So the
save() method performs an "update with upsert" and the document is inserted.

This is different from the case where a _id doesn't exist in the supplied
document; then save() actually will perform an "insert" operation.

This is sort of a nit. Use your best judgement.

--Norm

On Mon, Apr 14, 2014 at 4:59 PM, Kay Kim [email protected] wrote:

Hi Norm -- we currently have the following where the first sentence
encapsulates what the save() does and the following two explain exactly
what update w upsert does.

If the document contains an _id field, then the save() method performs an
update with upsert, querying by the _id field. If a document does not exist
with the specified _id value, the save() method performs an insert. If a
document exists with the specified _id value, the save() method performs an
update that replaces all fields in the existing document with the fields
from the document.

If you prefer, we could be more explicit in the relationship between the
sentences such as:

If the document contains an _id field, then the save() method performs an
update with upsert, querying by the _id field: i.e. if a document does not
exist with ... and if a document exists with the ...
-or-
With an update with upsert, if a document ... and if ...

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/1728#issuecomment-40432130
.

[kay-kim]

Then what I'll do is close this pull for now, but I opened up a
https://jira.mongodb.org/browse/DOCS-3163 to clarify "upsert"

since we might as well try to be thorough and consistent throughout the manual when we discuss upsert.

Kay