Navigation
This version of the documentation is archived and no longer supported.

Update Documents

This page provides examples of how to update documents in using the following methods in the mongo shell:

  • db.collection.updateOne(<filter>, <update>, <options>)
  • db.collection.updateMany(<filter>, <update>, <options>)
  • db.collection.replaceOne(<filter>, <replacement>, <options>)

This page provides examples of how to update documents using the following methods in the PyMongo Python driver:

  • pymongo.collection.Collection.update_one()
  • pymongo.collection.Collection.update_many()
  • pymongo.collection.Collection.replace_one()

This page provides examples of how to update documents using the following methods in the MongoDB Node.js Driver:

This page provides examples of how to update documents using the following methods in the MongoDB PHP Library:

  • MongoDB\Collection::updateOne()
  • MongoDB\Collection::updateMany()
  • MongoDB\Collection::replaceOne()

This page provides examples of how to update documents using the following methods in the MongoDB C# Driver:

This page provides examples of how to update documents using the following methods in the MongoDB Perl Driver:

This page provides examples of how to update documents using the following methods in the MongoDB Ruby Driver:

This page provides examples of how to update documents using the following methods in the MongoDB Scala Driver:

The examples on this page use the inventory collection. To create and/or populate the inventory collection, run the following:

db.inventory.insertMany( [
   { item: "canvas", qty: 100, size: { h: 28, w: 35.5, uom: "cm" }, status: "A" },
   { item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
   { item: "mat", qty: 85, size: { h: 27.9, w: 35.5, uom: "cm" }, status: "A" },
   { item: "mousepad", qty: 25, size: { h: 19, w: 22.85, uom: "cm" }, status: "P" },
   { item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" },
   { item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" },
   { item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" },
   { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" },
   { item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" },
   { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" }
]);

You can run the operation in the web shell below:

db.inventory.insert_many([
    {"item": "canvas",
     "qty": 100,
     "size": {"h": 28, "w": 35.5, "uom": "cm"},
     "status": "A"},
    {"item": "journal",
     "qty": 25,
     "size": {"h": 14, "w": 21, "uom": "cm"},
     "status": "A"},
    {"item": "mat",
     "qty": 85,
     "size": {"h": 27.9, "w": 35.5, "uom": "cm"},
     "status": "A"},
    {"item": "mousepad",
     "qty": 25,
     "size": {"h": 19, "w": 22.85, "uom": "cm"},
     "status": "P"},
    {"item": "notebook",
     "qty": 50,
     "size": {"h": 8.5, "w": 11, "uom": "in"},
     "status": "P"},
    {"item": "paper",
     "qty": 100,
     "size": {"h": 8.5, "w": 11, "uom": "in"},
     "status": "D"},
    {"item": "planner",
     "qty": 75,
     "size": {"h": 22.85, "w": 30, "uom": "cm"},
     "status": "D"},
    {"item": "postcard",
     "qty": 45,
     "size": {"h": 10, "w": 15.25, "uom": "cm"},
     "status": "A"},
    {"item": "sketchbook",
     "qty": 80,
     "size": {"h": 14, "w": 21, "uom": "cm"},
     "status": "A"},
    {"item": "sketch pad",
     "qty": 95,
     "size": {"h": 22.85, "w": 30.5, "uom": "cm"},
     "status": "A"}])
collection.insertMany(asList(
        Document.parse("{ item: 'canvas', qty: 100, size: { h: 28, w: 35.5, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'journal', qty: 25, size: { h: 14, w: 21, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'mat', qty: 85, size: { h: 27.9, w: 35.5, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'mousepad', qty: 25, size: { h: 19, w: 22.85, uom: 'cm' }, status: 'P' }"),
        Document.parse("{ item: 'notebook', qty: 50, size: { h: 8.5, w: 11, uom: 'in' }, status: 'P' }"),
        Document.parse("{ item: 'paper', qty: 100, size: { h: 8.5, w: 11, uom: 'in' }, status: 'D' }"),
        Document.parse("{ item: 'planner', qty: 75, size: { h: 22.85, w: 30, uom: 'cm' }, status: 'D' }"),
        Document.parse("{ item: 'postcard', qty: 45, size: { h: 10, w: 15.25, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'sketchbook', qty: 80, size: { h: 14, w: 21, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'sketch pad', qty: 95, size: { h: 22.85, w: 30.5, uom: 'cm' }, status: 'A' }")
));
db.collection('inventory').insertMany([
  { item: "canvas",
    qty: 100,
    size: {h: 28, w: 35.5, uom: "cm"},
    status: "A"},
  { item: "journal",
    qty: 25,
    size: {h: 14, w: 21, uom: "cm"},
    status: "A"},
  { item: "mat",
    qty: 85,
    size: {h: 27.9, w: 35.5, uom: "cm"},
    status: "A"},
  { item: "mousepad",
    qty: 25,
    size: {h: 19, w: 22.85, uom: "cm"},
    status: "P"},
  { item: "notebook",
    qty: 50,
    size: {h: 8.5, w: 11, uom: "in"},
    status: "P"},
  { item: "paper",
    qty: 100,
    size: {h: 8.5, w: 11, uom: "in"},
    status: "D"},
  { item: "planner",
    qty: 75,
    size: {h: 22.85, w: 30, uom: "cm"},
    status: "D"},
  { item: "postcard",
    qty: 45,
    size: {h: 10, w: 15.25, uom: "cm"},
    status: "A"},
  { item: "sketchbook",
    qty: 80,
    size: {h: 14, w: 21, uom: "cm"},
    status: "A"},
  { item: "sketch pad",
    qty: 95,
    size: {h: 22.85, w: 30.5, uom: "cm"},
    status: "A"}
])
.then(function(result) {
  // process result
})
$insertManyResult = $db->inventory->insertMany([
    [
        'item' => 'canvas',
        'qty' => 100,
        'size' => ['h' => 28, 'w' => 35.5, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'journal',
        'qty' => 25,
        'size' => ['h' => 14, 'w' => 21, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'mat',
        'qty' => 85,
        'size' => ['h' => 27.9, 'w' => 35.5, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'mousepad',
        'qty' => 25,
        'size' => ['h' => 19, 'w' => 22.85, 'uom' => 'cm'],
        'status' => 'P',
    ],
    [
        'item' => 'notebook',
        'qty' => 50,
        'size' => ['h' => 8.5, 'w' => 11, 'uom' => 'in'],
        'status' => 'P',
    ],
    [
        'item' => 'paper',
        'qty' => 100,
        'size' => ['h' => 8.5, 'w' => 11, 'uom' => 'in'],
        'status' => 'D',
    ],
    [
        'item' => 'planner',
        'qty' => 75,
        'size' => ['h' => 22.85, 'w' => 30, 'uom' => 'cm'],
        'status' => 'D',
    ],
    [
        'item' => 'postcard',
        'qty' => 45,
        'size' => ['h' => 10, 'w' => 15.25, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'sketchbook',
        'qty' => 80,
        'size' => ['h' => 14, 'w' => 21, 'uom' => 'cm'],
        'status' => 'A',
    ],
    [
        'item' => 'sketch pad',
        'qty' => 95,
        'size' => ['h' => 22.85, 'w' => 30.5, 'uom' => 'cm'],
        'status' => 'A',
    ],
]);
Publisher<Success> insertManyPublisher = collection.insertMany(asList(
        Document.parse("{ item: 'canvas', qty: 100, size: { h: 28, w: 35.5, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'journal', qty: 25, size: { h: 14, w: 21, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'mat', qty: 85, size: { h: 27.9, w: 35.5, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'mousepad', qty: 25, size: { h: 19, w: 22.85, uom: 'cm' }, status: 'P' }"),
        Document.parse("{ item: 'notebook', qty: 50, size: { h: 8.5, w: 11, uom: 'in' }, status: 'P' }"),
        Document.parse("{ item: 'paper', qty: 100, size: { h: 8.5, w: 11, uom: 'in' }, status: 'D' }"),
        Document.parse("{ item: 'planner', qty: 75, size: { h: 22.85, w: 30, uom: 'cm' }, status: 'D' }"),
        Document.parse("{ item: 'postcard', qty: 45, size: { h: 10, w: 15.25, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'sketchbook', qty: 80, size: { h: 14, w: 21, uom: 'cm' }, status: 'A' }"),
        Document.parse("{ item: 'sketch pad', qty: 95, size: { h: 22.85, w: 30.5, uom: 'cm' }, status: 'A' }")
));
var documents = new[]
{
    new BsonDocument
    {
        { "item", "canvas" },
        { "qty", 100 },
        { "size", new BsonDocument { { "h", 28 }, { "w", 35.5 }, { "uom", "cm" } } },
        { "status", "A" }
    },
    new BsonDocument
    {
        { "item", "journal" },
        { "qty", 25 },
        { "size", new BsonDocument { { "h", 14 }, { "w", 21 }, { "uom", "cm" } } },
        { "status", "A" }
    },
    new BsonDocument
    {
        { "item", "mat" },
        { "qty", 85 },
        { "size", new BsonDocument { { "h", 27.9 }, { "w", 35.5 }, { "uom", "cm" } } },
        { "status", "A" }
    },
    new BsonDocument
    {
        { "item", "mousepad" },
        { "qty", 25 },
        { "size", new BsonDocument { { "h", 19 }, { "w", 22.85 }, { "uom", "cm" } } },
        { "status", "P" }
    },
    new BsonDocument
    {
        { "item", "notebook" },
        { "qty", 50 },
        { "size", new BsonDocument { { "h", 8.5 }, { "w", 11 }, { "uom", "in" } } },
        { "status", "P" } },
    new BsonDocument
    {
        { "item", "paper" },
        { "qty", 100 },
        { "size", new BsonDocument { { "h", 8.5 }, { "w", 11 }, { "uom", "in" } } },
        { "status", "D" }
    },
    new BsonDocument
    {
        { "item", "planner" },
        { "qty", 75 },
        { "size", new BsonDocument { { "h", 22.85 }, { "w", 30 }, { "uom", "cm" } } },
        { "status", "D" }
    },
    new BsonDocument
    {
        { "item", "postcard" },
        { "qty", 45 },
        { "size", new BsonDocument { { "h", 10 }, { "w", 15.25 }, { "uom", "cm" } } },
        { "status", "A" }
    },
    new BsonDocument
    {
        { "item", "sketchbook" },
        { "qty", 80 },
        { "size", new BsonDocument { { "h", 14 }, { "w", 21 }, { "uom", "cm" } } },
        { "status", "A" }
    },
    new BsonDocument
    {
        { "item", "sketch pad" },
        { "qty", 95 },
        { "size", new BsonDocument { { "h", 22.85 }, { "w", 30.5 }, { "uom", "cm" } } }, { "status", "A" } },
};
collection.InsertMany(documents);
$db->coll("inventory")->insert_many(
    [
        {
            item   => "canvas",
            qty    => 100,
            size   => { h => 28, w => 35.5, uom => "cm" },
            status => "A"
        },
        {
            item   => "journal",
            qty    => 25,
            size   => { h => 14, w => 21, uom => "cm" },
            status => "A"
        },
        {
            item   => "mat",
            qty    => 85,
            size   => { h => 27.9, w => 35.5, uom => "cm" },
            status => "A"
        },
        {
            item   => "mousepad",
            qty    => 25,
            size   => { h => 19, w => 22.85, uom => "cm" },
            status => "P"
        },
        {
            item   => "notebook",
            qty    => 50,
            size   => { h => 8.5, w => 11, uom => "in" },
            status => "P"
        },
        {
            item   => "paper",
            qty    => 100,
            size   => { h => 8.5, w => 11, uom => "in" },
            status => "D"
        },
        {
            item   => "planner",
            qty    => 75,
            size   => { h => 22.85, w => 30, uom => "cm" },
            status => "D"
        },
        {
            item   => "postcard",
            qty    => 45,
            size   => { h => 10, w => 15.25, uom => "cm" },
            status => "A"
        },
        {
            item   => "sketchbook",
            qty    => 80,
            size   => { h => 14, w => 21, uom => "cm" },
            status => "A"
        },
        {
            item   => "sketch pad",
            qty    => 95,
            size   => { h => 22.85, w => 30.5, uom => "cm" },
            status => "A"
        }
    ]
);
client[:inventory].insert_many([
                                { item: 'canvas',
                                  qty: 100,
                                  size: { h: 28, w: 35.5, uom: 'cm' },
                                  status: 'A' },
                                { item: 'journal',
                                  qty: 25,
                                  size: { h: 14, w: 21, uom: 'cm' },
                                  status: 'A' },
                                { item: 'mat',
                                  qty: 85,
                                  size: { h: 27.9, w: 35.5, uom: 'cm' },
                                  status: 'A' },
                                { item: 'mousepad',
                                  qty: 25,
                                  size: { h: 19, w: 22.85, uom: 'cm' },
                                  status: 'P' },
                                { item: 'notebook',
                                  qty: 50,
                                  size: { h: 8.5, w: 11, uom: 'in' },
                                  status: 'P' },
                                { item: 'paper',
                                  qty: 100,
                                  size: { h: 8.5, w: 11, uom: 'in' },
                                  status: 'D' },
                                { item: 'planner',
                                  qty: 75,
                                  size: { h: 22.85, w: 30, uom: 'cm' },
                                  status: 'D' },
                                { item: 'postcard',
                                  qty: 45,
                                  size: { h: 10, w: 15.25, uom: 'cm' },
                                  status: 'A' },
                                { item: 'sketchbook',
                                  qty: 80,
                                  size: { h: 14, w: 21, uom: 'cm' },
                                  status: 'A' },
                                { item: 'sketch pad',
                                  qty: 95,
                                  size: { h: 22.85, w: 30.5, uom: 'cm' },
                                  status: 'A' }
                              ])
collection.insertMany(Seq(
  Document("""{ item: "canvas", qty: 100, size: { h: 28, w: 35.5, uom: "cm" }, status: "A" }"""),
  Document("""{ item: "journal", qty: 25, size: { h: 14, w: 21, uom: "cm" }, status: "A" }"""),
  Document("""{ item: "mat", qty: 85, size: { h: 27.9, w: 35.5, uom: "cm" }, status: "A" }"""),
  Document("""{ item: "mousepad", qty: 25, size: { h: 19, w: 22.85, uom: "cm" }, status: "P" }"""),
  Document("""{ item: "notebook", qty: 50, size: { h: 8.5, w: 11, uom: "in" }, status: "P" }"""),
  Document("""{ item: "paper", qty: 100, size: { h: 8.5, w: 11, uom: "in" }, status: "D" }"""),
  Document("""{ item: "planner", qty: 75, size: { h: 22.85, w: 30, uom: "cm" }, status: "D" }"""),
  Document("""{ item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }"""),
  Document("""{ item: "sketchbook", qty: 80, size: { h: 14, w: 21, uom: "cm" }, status: "A" }"""),
  Document("""{ item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" }""")
)).execute()

Update Documents in a Collection

To update a document, MongoDB provides update operators, such as $set, to modify field values.

To use the update operators, pass to the update methods an update document of the form:

{
  <update operator>: { <field1>: <value1>, ... },
  <update operator>: { <field2>: <value2>, ... },
  ...
}

To use the update operators, pass to the update methods an update document of the form:

{
  <update operator>: { <field1>: <value1>, ... },
  <update operator>: { <field2>: <value2>, ... },
  ...
}

The driver provides the com.mongodb.client.model.Updates class to facilitate the creation of update documents. For example:

combine(set( <field1>, <value1>), set(<field2>, <value2> ) )

For a list of the update helpers, see com.mongodb.client.model.Updates.

{
  <update operator>: { <field1>: <value1>, ... },
  <update operator>: { <field2>: <value2>, ... },
  ...
}

To use the update operators, pass to the update methods an update document of the form:

[
  <update operator> => [ <field1> => <value1>, ... ],
  <update operator> => [ <field2> => <value2>, ... ],
  ...
]

The driver provides the com.mongodb.client.model.Updates class to facilitate the creation of update documents. For example:

combine(set( <field1>, <value1>), set(<field2>, <value2> ) )

For a list of the update helpers, see com.mongodb.client.model.Updates.

{
  <update operator> => { <field1> => <value1>, ... },
  <update operator> => { <field2> => <value2>, ... },
  ...
}

To use the update operators, pass to the update methods an update document of the form:

{
  <update operator> => { <field1> => <value1>, ... },
  <update operator> => { <field2> => <value2>, ... },
  ...
}
{
  <update operator> => { <field1> => <value1>, ... },
  <update operator> => { <field2> => <value2>, ... },
  ...
}

To use the update operators, pass to the update methods an update document of the form:

(
  set (<field1>, <value1>),
  set (<field2>, <value2>),
  ...
)

Some update operators, such as $set, will create the field if the field does not exist. See the individual update operator reference for details.

Update a Single Document

The following example uses the db.collection.updateOne() method on the inventory collection to update the first document where item equals "paper":

The following example uses the update_one() method on the inventory collection to update the first document where item equals "paper":

The following example uses the com.mongodb.client.MongoCollection.updateOne method on the inventory collection to update the first document where item equals "paper":

The following example uses the Collection.updateOne() method on the inventory collection to update the first document where item equals "paper":

The following example uses the updateOne() method on the inventory collection to update the first document where item equals "paper":

The following example uses the com.mongodb.reactivestreams.client.MongoCollection.updateOne on the inventory collection to update the first document where item equals "paper":

The following example uses the IMongoCollection.UpdateOne() method on the inventory collection to update the first document where item equals "paper":

The following example uses the update_one() method on the inventory collection to update the first document where item equals "paper":

The following example uses the update_one() method on the inventory collection to update the first document where item equals "paper":

The following example uses the updateOne() method on the inventory collection to update the first document where item equals "paper":

db.inventory.updateOne(
   { item: "paper" },
   {
     $set: { "size.uom": "cm", status: "P" },
     $currentDate: { lastModified: true }
   }
)
db.inventory.update_one(
    {"item": "paper"},
    {"$set": {"size.uom": "cm", "status": "P"},
     "$currentDate": {"lastModified": True}})
collection.updateOne(eq("item", "paper"),
        combine(set("size.uom", "cm"), set("status", "P"), currentDate("lastModified")));
db.collection('inventory').updateOne(
  { item: "paper" },
  { $set: { "size.uom": "cm", status: "P" },
    $currentDate: { lastModified: true } })
.then(function(result) {
  // process result
})            
$updateResult = $db->inventory->updateOne(
    ['item' => 'paper'],
    [
        '$set' => ['size.uom' => 'cm', 'status' => 'P'],
        '$currentDate' => ['lastModified' => true],
    ]
);
Publisher<UpdateResult> updateOnePublisher = collection.updateOne(eq("item", "paper"),
        combine(set("size.uom", "cm"), set("status", "P"), currentDate("lastModified")));
var filter = Builders<BsonDocument>.Filter.Eq("item", "paper");
var update = Builders<BsonDocument>.Update.Set("size.uom", "cm").Set("status", "P").CurrentDate("lastModified");
var result = collection.UpdateOne(filter, update);
# For boolean values, use boolean.pm for 'true' and 'false'
$db->coll("inventory")->update_one(
    { item => "paper" },
    {
        '$set'         => { "size.uom"   => "cm", status => "P" },
        '$currentDate' => { lastModified => true }
    }
);
client[:inventory].update_one({ item: 'paper'},
                              { '$set' => { 'size.uom' => 'cm', 'status' => 'P' },
                                '$currentDate' => { 'lastModified' => true } })
collection.updateOne(equal("item", "paper"),
  combine(set("size.uom", "cm"), set("status", "P"), currentDate("lastModified"))
).execute()

The update operation:

  • uses the $set operator to update the value of the size.uom field to "cm" and the value of the status field to "P",
  • uses the $currentDate operator to update the value of the lastModified field to the current date. If lastModified field does not exist, $currentDate will create the field. See $currentDate for details.

Update Multiple Documents

New in version 3.2.

The following example uses the db.collection.updateMany() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the update_many() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the com.mongodb.client.MongoCollection.updateMany method on the inventory collection to update all documents where qty is less than 50:

The following example uses the Collection.updateMany() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the updateMany() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the com.mongodb.reactivestreams.client.MongoCollection.updateMany method on the inventory collection to update all documents where qty is less than 50:

The following example uses the IMongoCollection.UpdateMany() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the update_many() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the update_many() method on the inventory collection to update all documents where qty is less than 50:

The following example uses the updateMany() method on the inventory collection to update all documents where qty is less than 50:

db.inventory.updateMany(
   { "qty": { $lt: 50 } },
   {
     $set: { "size.uom": "in", status: "P" },
     $currentDate: { lastModified: true }
   }
)
db.inventory.update_many(
    {"qty": {"$lt": 50}},
    {"$set": {"size.uom": "in", "status": "P"},
     "$currentDate": {"lastModified": True}})
collection.updateMany(lt("qty", 50),
        combine(set("size.uom", "in"), set("status", "P"), currentDate("lastModified")));
db.collection('inventory').updateMany(
  { qty: { $lt: 50 } },
  { $set: { "size.uom": "in", status: "P" },
    $currentDate: { lastModified: true } })
.then(function(result) {
  // process result
})            
$updateResult = $db->inventory->updateMany(
    ['qty' => ['$lt' => 50]],
    [
        '$set' => ['size.uom' => 'cm', 'status' => 'P'],
        '$currentDate' => ['lastModified' => true],
    ]
);
Publisher<UpdateResult> updateManyPublisher = collection.updateMany(lt("qty", 50),
        combine(set("size.uom", "in"), set("status", "P"), currentDate("lastModified")));
var filter = Builders<BsonDocument>.Filter.Lt("qty", 50);
var update = Builders<BsonDocument>.Update.Set("size.uom", "in").Set("status", "P").CurrentDate("lastModified");
var result = collection.UpdateMany(filter, update);
# For boolean values, use boolean.pm for 'true' and 'false'
$db->coll("inventory")->update_many(
    { qty => { '$lt' => 50 } },
    {
        '$set'         => { "size.uom"   => "in", status => "P" },
        '$currentDate' => { lastModified => true }
    }
);
client[:inventory].update_many({ qty: { '$lt' => 50 } },
                              { '$set' => { 'size.uom' => 'in', 'status' => 'P' },
                                '$currentDate' => { 'lastModified' => true } })
collection.updateMany(lt("qty", 50),
  combine(set("size.uom", "in"), set("status", "P"), currentDate("lastModified"))
).execute()

The update operation:

  • uses the $set operator to update the value of the size.uom field to "in" and the value of the status field to "P",
  • uses the $currentDate operator to update the value of the lastModified field to the current date. If lastModified field does not exist, $currentDate will create the field. See $currentDate for details.

Replace a Document

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to db.collection.replaceOne().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to replace_one().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to com.mongodb.client.MongoCollection.replaceOne.

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to Collection.replaceOne().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to replaceOne().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to com.mongodb.reactivestreams.client.MongoCollection.replaceOne.

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to IMongoCollection.ReplaceOne().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to replace_one().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to replace_one().

To replace the entire content of a document except for the _id field, pass an entirely new document as the second argument to replaceOne()

When replacing a document, the replacement document must consist of only field/value pairs; i.e. do not include update operators expressions.

The replacement document can have different fields from the original document. In the replacement document, you can omit the _id field since the _id field is immutable; however, if you do include the _id field, it must have the same value as the current value.

The following example replaces the first document from the inventory collection that matches the filter item equals "paper":

db.inventory.replaceOne(
   { item: "paper" },
   { item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 40 } ] }
)
db.inventory.replace_one(
    {"item": "paper"},
    {"item": "paper",
     "instock": [
         {"warehouse": "A", "qty": 60},
         {"warehouse": "B", "qty": 40}]})
collection.replaceOne(eq("item", "paper"),
        Document.parse("{ item: 'paper', instock: [ { warehouse: 'A', qty: 60 }, { warehouse: 'B', qty: 40 } ] }"));
db.collection('inventory').replaceOne(
  { item: "paper" },
  { item: "paper", 
    instock: [
      { warehouse: "A", qty: 60 },
      { warehouse: "B", qty: 40 }
    ]})
.then(function(result) {
  // process result
})
$updateResult = $db->inventory->replaceOne(
    ['item' => 'paper'],
    [
        'item' => 'paper',
        'instock' => [
            ['warehouse' => 'A', 'qty' => 60],
            ['warehouse' => 'B', 'qty' => 40],
        ],
    ]
);
Publisher<UpdateResult> replaceOnePublisher = collection.replaceOne(eq("item", "paper"),
        Document.parse("{ item: 'paper', instock: [ { warehouse: 'A', qty: 60 }, { warehouse: 'B', qty: 40 } ] }"));
var filter = Builders<BsonDocument>.Filter.Eq("item", "paper");
var replacement = new BsonDocument
{
    { "item", "paper" },
    { "instock", new BsonArray
        {
            new BsonDocument { { "warehouse", "A" }, { "qty", 60 } },
            new BsonDocument { { "warehouse", "B" }, { "qty", 40 } } }
        }
};
var result = collection.ReplaceOne(filter, replacement);
$db->coll("inventory")->replace_one(
    { item => "paper" },
    {
        item    => "paper",
        instock => [ { warehouse => "A", qty => 60 }, { warehouse => "B", qty => 40 } ]
    }
);
client[:inventory].replace_one({ item: 'paper' },
                               { item: 'paper',
                                 instock: [ { warehouse: 'A', qty: 60 },
                                            { warehouse: 'B', qty: 40 } ] })
collection.replaceOne(equal("item", "paper"),
  Document("""{ item: "paper", instock: [ { warehouse: "A", qty: 60 }, { warehouse: "B", qty: 40 } ] }""")
).execute()

Behavior

Atomicity

All write operations in MongoDB are atomic on the level of a single document. For more information on MongoDB and atomicity, see Atomicity and Transactions.

_id Field

Once set, you cannot update the value of the _id field nor can you replace an existing document with a replacement document that has a different _id field value.

Document Size

For MMAPv1, when performing update operations that increase the document size beyond the allocated space for that document, the update operation relocates the document on disk.

Field Order

MongoDB preserves the order of the document fields following write operations except for the following cases:

  • The _id field is always the first field in the document.
  • Updates that include renaming of field names may result in the reordering of fields in the document.

Changed in version 2.6: Starting in version 2.6, MongoDB actively attempts to preserve the field order in a document. Before version 2.6, MongoDB did not actively preserve the order of the fields in a document.

Upsert Option

If updateOne(), updateMany(), or replaceOne() includes upsert : true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If update_one(), update_many(), or replace_one() includes upsert : true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If the update and replace methods include the com.mongodb.client.model.UpdateOptions parameter that specifies com.mongodb.client.model.UpdateOptions.upsert(true) and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If updateOne(), updateMany(), or replaceOne() include upsert : true in the options parameter document and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If updateOne(), updateMany(), or replaceOne() includes upsert => true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If the update and replace methods include the UpdateOptions parameter that specifies UpdateOptions.upsert(true) and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If UpdateOne(), UpdateMany(), or ReplaceOne() includes an UpdateOptions argument instance with the IsUpsert option set to true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If update_one(), update_many(), or replace_one() includes upsert => true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If update_one(), update_many(), or replace_one() includes upsert => true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

If updateOne(), updateMany(), or replaceOne() includes upsert => true and no documents match the specified filter, then the operation creates a new document and inserts it. If there are matching documents, then the operation modifies or replaces the matching document or documents.

For details on the new document created, see the individual reference pages for the methods.

Write Acknowledgement

With write concerns, you can specify the level of acknowledgement requested from MongoDB for write operations. For details, see Write Concern.