- Reference >
mongo
Shell Methods >- Collection Methods >
- db.collection.updateOne()
db.collection.updateOne()¶
On this page
Definition¶
-
db.collection.
updateOne
(filter, update, options)¶ New in version 3.2.
Updates a single document within the collection based on the filter.
The
updateOne()
method has the following form:The
updateOne()
method takes the following parameters:Parameter Type Description filter
document The selection criteria for the update. The same query selectors as in the
find()
method are available.Specify an empty document
{ }
to update the first document returned in the collection.update
document The modifications to apply.
Use Update Operators such as
$set
,$unset
, or$rename
.Using the update() pattern of
field: value
for theupdate
parameter throws an error.upsert
boolean Optional. When
true
,updateOne()
either:- Creates a new document if no documents match the
filter
. For more details see upsert behavior. - Updates a single document that matches the
filter
.
To avoid multiple upserts, ensure that the
filter
fields are uniquely indexed.Defaults to
false
.writeConcern
document Optional. A document expressing the write concern. Omit to use the default write concern. Returns: A document containing: - A boolean
acknowledged
astrue
if the operation ran with write concern orfalse
if write concern was disabled matchedCount
containing the number of matched documentsmodifiedCount
containing the number of modified documentsupsertedId
containing the_id
for the upserted document
- Creates a new document if no documents match the
Behavior¶
updateOne()
updates the first matching document in
the collection that matches the filter
, using the update
instructions
to apply modifications.
If upsert: true
and no documents match the filter
,
updateOne()
creates a new
document based on the filter
criteria and update
modifications. See
Update with Upsert.
Capped Collection¶
If an update operation changes the document size, the operation will fail.
Examples¶
Update¶
The restaurant
collection contains the following documents:
The following operation updates a single document where
name: "Central Perk Cafe"
with the violations
field:
The operation returns:
If no matches were found, the operation instead returns:
Setting upsert: true
would insert the document if no match was found. See
Update with Upsert
Update with Upsert¶
The restaurant
collection contains the following documents:
The following operation attempts to update the document with
name : "Pizza Rat's Pizzaria"
, while upsert: true
:
Since upsert:true
the document is inserted
based on the filter
and
update
criteria. The operation returns:
The collection now contains the following documents:
The name
field was filled in using the filter
criteria, while the
update
operators were used to create the rest of the document.
The following operation updates the first document with violations
that
are greater than 10
:
The operation returns:
The collection now contains the following documents:
Since no documents matched the filter, and upsert
was true
,
updateOne
inserted the document with a generated
_id
and the update
criteria only.
Update with Write Concern¶
Given a three member replica set, the following operation specifies a
w
of majority
, wtimeout
of 100
:
If the primary and at least one secondary acknowledge each write operation within 100 milliseconds, it returns:
If the acknowledgement takes longer than the wtimeout
limit, the following
exception is thrown:
See also
To update multiple documents, see
db.collection.updateMany()
.