update-documents.txt

.. include:: /includes/java-sync-links.rst
.. include:: /includes/java-async-links.rst

.. _write-op-update:

================
Update Documents
================

.. default-domain:: mongodb

.. facet::
   :name: programming_language
   :values: shell, csharp, go, java, python, perl, php, ruby, rust, scala, javascript/typescript, kotlin

.. meta::
   :description: How to update single or multiple documents in MongoDB. How to update all  or replace documents in MongoDB. How to update fields in documents in MongoDB. 
   :keywords: update collection, motor, java sync, java async, reactive streams, code example, node.js, compass, coroutine

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1

You can update documents in MongoDB using the following methods:

- Your programming language's driver.
- The :atlas:`{+atlas+} UI </>`. To learn more, see 
  :ref:`update-documents-atlas-ui`.
- :compass:`MongoDB Compass </>`.

----------

.. |arrow| unicode:: U+27A4

|arrow| Use the **Select your language** drop-down menu in the
upper-right to set the language of the following examples.

----------

.. |populate-inventory| replace:: The examples on this page use the
   ``inventory`` collection. Connect to a test database in your MongoDB
   instance then create the ``inventory`` collection:

.. tabs-selector:: drivers

.. tabs-drivers::

   .. tab::
      :tabid: shell

      This page uses the following :binary:`~bin.mongosh` methods:

      - :method:`db.collection.updateOne(\<filter\>, \<update\>, \<options\>) <db.collection.updateOne>`

      - :method:`db.collection.updateMany(\<filter\>, \<update\>, \<options\>) <db.collection.updateMany>`

      - :method:`db.collection.replaceOne(\<filter\>, \<update\>, \<options\>) <db.collection.replaceOne>`

      |populate-inventory|

   .. tab::
      :tabid: compass

      This page uses :ref:`MongoDB Compass <compass-index>` to
      update the documents.

      The examples on this page use the ``inventory`` collection.
      Populate the ``inventory`` collection with the following
      documents:

   .. tab::
      :tabid: c

      This page uses the following `MongoDB C Driver <https://mongoc.org/libmongoc/current/index.html>`__
      methods:

      - `mongoc_collection_update_one <https://mongoc.org/libmongoc/current/mongoc_collection_update_one.html>`__
      - `mongoc_collection_replace_one <https://mongoc.org/libmongoc/current/mongoc_collection_replace_one.html>`__
      
      |populate-inventory|

   .. tab::
      :tabid: python

      This page uses the following
      `PyMongo <https://pymongo.readthedocs.io/en/stable/index.html>`__
      Python driver methods:

      - :py:meth:`pymongo.collection.Collection.update_one`

      - :py:meth:`pymongo.collection.Collection.update_many`

      - :py:meth:`pymongo.collection.Collection.replace_one`
      
      |populate-inventory|

   .. tab::
      :tabid: motor

      This page uses the
      following `Motor <https://motor.readthedocs.io/en/stable/>`_
      driver methods:

      - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one`

      - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many`

      - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one`

      |populate-inventory|

   .. tab::
      :tabid: java-sync

      This page uses the
      following `Java Synchronous Driver`_ methods:

      - com.mongodb.client.MongoCollection.updateOne_

      - com.mongodb.client.MongoCollection.updateMany_

      - com.mongodb.client.MongoCollection.replaceOne_

      |populate-inventory|

   .. tab::
      :tabid: java-async

      This page uses the
      following `Java Reactive Streams Driver
      <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/>`_ methods:

      - `com.mongodb.reactivestreams.client.MongoCollection.updateOne
        <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_

      - `com.mongodb.reactivestreams.client.MongoCollection.updateMany
        <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_

      - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne
        <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,%20TDocument)>`_

      |populate-inventory|

   .. tab::
      :tabid: kotlin-coroutine

      This page uses the
      following :driver:`Kotlin Coroutine Driver </kotlin/coroutine/current/>` methods:

      - `MongoCollection.updateOne() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-one.html>`__
      - `MongoCollection.updateMany() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-many.html>`__
      - `MongoCollection.replaceOne() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/replace-one.html>`__

      |populate-inventory|

   .. tab::
      :tabid: nodejs

      This page uses the
      following :node-docs:`MongoDB Node.js Driver <>` methods:

      - :node-api:`Collection.updateOne() <Collection.html#updateOne>`

      - :node-api:`Collection.updateMany() <Collection.html#updateMany>`

      - :node-api:`Collection.replaceOne() <Collection.html#replaceOne>`

      |populate-inventory|

   .. tab::
      :tabid: php

      This page uses the following  `MongoDB PHP Library
      <https://www.mongodb.com/docs/php-library/current/>`_ methods:

      - :phpmethod:`MongoDB\\Collection::updateOne() <phpmethod.MongoDB\\Collection::updateOne()>`

      - :phpmethod:`MongoDB\\Collection::updateMany() <phpmethod.MongoDB\\Collection::updateMany()>`

      - :phpmethod:`MongoDB\\Collection::replaceOne() <phpmethod.MongoDB\\Collection::replaceOne()>`

      |populate-inventory|

   .. tab::
      :tabid: perl

      This page uses the following  `MongoDB Perl Driver
      <https://metacpan.org/release/MongoDB>`_ methods:

      - :perl-api:`MongoDB::Collection::update_one()<Collection#update_one>`

      - :perl-api:`MongoDB::Collection::update_many()<Collection#update_many>`

      - :perl-api:`MongoDB::Collection::replace_one()<Collection#replace_one>`

      |populate-inventory|

   .. tab::
      :tabid: ruby

      This page uses the following :ruby:`MongoDB Ruby Driver </>` methods:

      - :ruby-api:`Mongo::Collection#update_one()<Collection.html#update_one-instance_method>`

      - :ruby-api:`Mongo::Collection#update_many()<Collection.html#update_many-instance_method>`

      - :ruby-api:`Mongo::Collection#replace_one()<Collection.html#replace_one-instance_method>`

      |populate-inventory|

   .. tab::
      :tabid: scala

      This page uses the following  `MongoDB Scala Driver
      <http://mongodb.github.io/mongo-scala-driver/>`_ methods:

      - :scala-api:`collection.updateOne()<updateOne(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

      - :scala-api:`collection.updateMany()<updateMany(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

      - :scala-api:`collection.replaceOne()<replaceOne(filter:org.mongodb.scala.bson.conversions.Bson,replacement:TResult,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

      |populate-inventory|

   .. tab::
      :tabid: csharp

      This page uses the following :driver:`MongoDB C# Driver </csharp/>` methods:

      - :csharp-api:`IMongoCollection.UpdateOne()<M_MongoDB_Driver_IMongoCollection_1_UpdateOne>`

      - :csharp-api:`IMongoCollection.UpdateMany()<M_MongoDB_Driver_IMongoCollection_1_UpdateMany>`

      - :csharp-api:`IMongoCollection.ReplaceOne() <M_MongoDB_Driver_IMongoCollection_1_ReplaceOne>`

      |populate-inventory|

   .. tab::
      :tabid: go

      This page uses the following :driver:`MongoDB Go Driver </go/>` functions:

      - :go-api:`Collection.UpdateOne<mongo#Collection.UpdateOne>`

      - :go-api:`Collection.UpdateMany<mongo#Collection.UpdateMany>`

      - :go-api:`Collection.ReplaceOne <mongo#Collection.ReplaceOne>`

      |populate-inventory|

.. include:: /includes/driver-examples/driver-example-update-51.rst

.. _update-documents-modifiers:

Update Documents in a Collection
--------------------------------

.. tabs-drivers::

   .. tab::
      :tabid: shell

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>`, such
      as :update:`$set`, to modify field values.

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

      .. code-block:: javascript

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: compass

      To update a document in Compass, hover over the target
      document and click the pencil icon:

      .. figure:: /images/compass-update-doc-button.png
         :alt: Click edit document

      After clicking the pencil icon, the document enters edit mode:

      .. figure:: /images/compass-update-edit-mode.png
         :alt: Document edit mode

      You can now change the this document by clicking the item you wish
      to change and modifying the value.

      For detailed instructions on updating documents in Compass,
      refer to the
      :ref:`Compass documentation <compass-modify-documents>`
      or follow the :ref:`example <write-op-updateOne>` below.

      Once you are satisfied with your changes, click
      :guilabel:`Update` to save the updated document.

      Click :guilabel:`Cancel` to revert any modifications made to
      the document and exit edit mode.

   .. tab::
      :tabid: python

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: python

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: motor

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: python

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: java-sync

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

      The driver provides the `com.mongodb.client.model.Updates
      <http://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/Updates.html>`__
      class to facilitate the creation of update documents. For example:

      .. code-block:: java

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

      For a list of the update helpers, see
      `com.mongodb.client.model.Updates
      <http://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/Updates.html>`__.

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: java-async

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

      The driver provides the `com.mongodb.client.model.Updates
      <http://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/Updates.html>`__
      class to facilitate the creation of update documents. For example:

      .. code-block:: java

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

      For a list of the update helpers, see
      `com.mongodb.client.model.Updates
      <http://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/Updates.html>`__.

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: kotlin-coroutine

      To update a document, MongoDB provides
      :ref:`update operators <update-operators>` such
      as :update:`$set` to modify field values.

      The driver provides the `com.mongodb.client.model.Updates
      <{+java-api-docs+}/mongodb-driver-core/com/mongodb/client/model/Updates.html>`__
      class to facilitate the creation of update documents. The
      following code shows an update document that uses methods
      from the ``Updates`` builder class:

      .. code-block:: kotlin

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: nodejs

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: javascript

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: php

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: php

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: perl

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: perl

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: ruby

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: ruby

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: csharp

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: c#

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: scala

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

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

      .. code-block:: scala

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

      .. include:: /includes/fact-update-set-create-fields.rst

   .. tab::
      :tabid: go

      To update a document, MongoDB provides
      :manual:`update operators </reference/operator/update>` such
      as :update:`$set` to modify field values.

      .. include:: /includes/fact-update-set-create-fields.rst

.. note::

   MongoDB can accept an aggregation pipeline to specify the modifications to 
   make instead of an update document. For details, see the method reference 
   page.
   
.. _write-op-updateOne:

Update a Single Document
~~~~~~~~~~~~~~~~~~~~~~~~

.. tabs-drivers::

   .. tab::
      :tabid: shell

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

   .. tab::
      :tabid: compass

      The following example demonstrates using |compass| to modify
      a single document where ``item: paper`` in the ``inventory``
      collection:

      .. note::

         This example uses the Compass
         :ref:`Table View <documents-table-view>` to modify the
         document. The editing process using the Compass
         :ref:`List View <documents-list-view>` follows a very
         similar approach.

         For more information on the differences between Table View
         and List View in Compass, refer to the
         :ref:`Compass documentation <compass-view-documents>`.

   .. tab::
      :tabid: python

      The following example uses the
      :py:meth:`~pymongo.collection.Collection.update_one` method on
      the ``inventory`` collection to update the *first* document
      where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: motor

      The following example uses the
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`
      method on the ``inventory`` collection to update the *first*
      document where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: java-sync

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

   .. tab::
      :tabid: java-async

      The following example uses the
      `com.mongodb.reactivestreams.client.MongoCollection.updateOne
      <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_
      on the ``inventory`` collection to update the *first* document
      where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: kotlin-coroutine

      The following example uses the
      `MongoCollection.updateOne()
      <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-one.html>`__
      method on the ``inventory`` collection to update the *first*
      document where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: nodejs

      The following example uses the
      :node-api:`Collection.updateOne() <Collection.html#updateOne>`
      method on the ``inventory`` collection to update the *first*
      document where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: php

      The following example uses the :phpmethod:`updateOne()
      <phpmethod.MongoDB\\Collection::updateOne()>` method on the
      ``inventory`` collection to update the *first* document where
      ``item`` equals ``"paper"``:

   .. tab::
      :tabid: perl

      The following example uses the
      :perl-api:`update_one()<Collection#update_one>` method on the
      ``inventory`` collection to update the *first* document where
      ``item`` equals ``"paper"``:

   .. tab::
      :tabid: ruby

      The following example uses the
      :ruby-api:`update_one()<Collection.html#update_one-instance_method>`
      method on the ``inventory`` collection to update the *first*
      document where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: scala

      The following example uses the
      :scala-api:`updateOne()<updateOne(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`
      method on the ``inventory`` collection to update the *first*
      document where ``item`` equals ``"paper"``:

   .. tab::
      :tabid: csharp

      The following example uses the
      :csharp-api:`IMongoCollection.UpdateOne()
      <M_MongoDB_Driver_IMongoCollection_1_UpdateOne>` method on the
      ``inventory`` collection to update the *first* document where
      ``item`` equals ``"paper"``:

   .. tab::
      :tabid: go

      The following example uses the
      :go-api:`Collection.UpdateOne<mongo#Collection.UpdateOne>` method
      on the ``inventory`` collection to update the *first* document
      where ``item`` equals ``"paper"``:

.. include:: /includes/driver-examples/driver-example-update-52.rst

.. _update-multiple-documents:
.. _write-op-updateMany:

Update Multiple Documents
~~~~~~~~~~~~~~~~~~~~~~~~~

.. tabs-drivers::

   .. tab::
      :tabid: compass

      You can update only one document at a time in |compass|.
      To update multiple documents, connect to your 
      MongoDB deployment from :binary:`~bin.mongosh` or a MongoDB driver
      and follow the examples in this section for your preferred method.

   .. tab::
      :tabid: shell

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

   .. tab::
      :tabid: python

      The following example uses the
      :py:meth:`~pymongo.collection.Collection.update_many` method on
      the ``inventory`` collection to update all documents where ``qty``
      is less than ``50``:

   .. tab::
      :tabid: motor

      The following example uses the
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

   .. tab::
      :tabid: java-sync

      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``:

   .. tab::
      :tabid: java-async

      The following example uses the
      `com.mongodb.reactivestreams.client.MongoCollection.updateMany
      <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

   .. tab::
      :tabid: kotlin-coroutine

      The following example uses the
      `MongoCollection.updateMany()
      <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-many.html>`__
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

   .. tab::
      :tabid: nodejs

      The following example uses the :node-api:`Collection.updateMany()
      <Collection.html#updateMany>` method on the ``inventory``
      collection to update all documents where ``qty`` is less than
      ``50``:

   .. tab::
      :tabid: php

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

   .. tab::
      :tabid: perl

      The following example uses the
      :perl-api:`update_many()<Collection#update_many>` method on the
      ``inventory`` collection to update all documents where ``qty`` is
      less than ``50``:

   .. tab::
      :tabid: ruby

      The following example uses the
      :ruby-api:`update_many()<Collection.html#update_many-instance_method>`
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

   .. tab::
      :tabid: scala

      The following example uses the
      :scala-api:`updateMany()<updateMany(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

   .. tab::
      :tabid: csharp

      The following example uses the
      :csharp-api:`IMongoCollection.UpdateMany()
      <M_MongoDB_Driver_IMongoCollection_1_UpdateMany>` method on the
      ``inventory`` collection to update all documents where ``qty`` is
      less than ``50``:

   .. tab::
      :tabid: go

      The following example uses the
      :go-api:`Collection.UpdateMany<mongo#Collection.UpdateMany>`
      method on the ``inventory`` collection to update all documents
      where ``qty`` is less than ``50``:

.. include:: /includes/driver-examples/driver-example-update-53.rst

Replace a Document
~~~~~~~~~~~~~~~~~~

.. tabs-drivers::

   .. tab::
      :tabid: compass

      You can't replace a document in |compass|.
      To replace a document, connect to your 
      MongoDB deployment from :binary:`~bin.mongosh` or a MongoDB driver
      and follow the examples in this section for your preferred method.

   .. tab::
      :tabid: shell

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

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: python

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :py:meth:`~pymongo.collection.Collection.replace_one`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: motor

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.replace_one`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: java-sync

      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_.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: java-async

      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
      <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,%20TDocument)>`_.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: kotlin-coroutine

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      the `MongoCollection.replaceOne() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/replace-one.html>`__ method.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: nodejs

      To replace the entire content of a document except for the
      ``_id`` field, pass an entirely new document as the second
      argument to
      :node-api:`Collection.replaceOne() <Collection.html#replaceOne>`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: php

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :phpmethod:`replaceOne()
      <phpmethod.MongoDB\\Collection::replaceOne()>`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: perl

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :perl-api:`replace_one()<Collection#replace_one>`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: ruby

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :ruby-api:`replace_one()<Collection.html#replace_one-instance_method>`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: scala

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :scala-api:`replaceOne()<replaceOne(filter:org.mongodb.scala.bson.conversions.Bson,replacement:TResult,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: csharp

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :csharp-api:`IMongoCollection.ReplaceOne()
      <M_MongoDB_Driver_IMongoCollection_1_ReplaceOne>`.

      .. include:: /includes/fact-update-replace-example.rst

   .. tab::
      :tabid: go

      To replace the entire content of a document except for the ``_id``
      field, pass an entirely new document as the second argument to
      :go-api:`Collection.ReplaceOne <mongo#Collection.ReplaceOne>`.

      .. include:: /includes/fact-update-replace-example.rst

.. include:: /includes/driver-examples/driver-example-update-54.rst

.. _update-documents-atlas-ui:

Update a Document with {+atlas+}
------------------------------------

.. note:: 

   You can update only one document at a time in the {+atlas+} UI.
   To update multiple documents or replace an entire document, 
   connect to your Atlas deployment from :binary:`~bin.mongosh` 
   or a MongoDB driver and follow the examples on this page 
   for your preferred method.

The example in this section uses the :atlas:`sample supplies dataset 
</sample-data/sample-supplies/>`. To learn how to load the sample dataset 
into your {+atlas+} deployment, see :atlas:`Load Sample Data 
</sample-data/#std-label-load-sample-data>`.

To update a document in {+atlas+}, follow these steps:

.. procedure:: 
   :style: normal

   .. step:: Navigate to the collection.

      a. In the {+atlas+} UI, click :guilabel:`Database` in the sidebar.
      #. For the database deployment that contains the sample data, click :guilabel:`Browse Collections`.
      #. In the left navigation pane, select the ``sample_supplies`` database.
      #. Select the ``sales`` collection.

   .. step:: Specify a query filter document.

      You can specify a :ref:`query filter document <document-query-filter>`
      in the :guilabel:`Filter` field. A query filter document uses 
      :ref:`query operators <csfle-supported-query-operators>` to specify search conditions.

      Copy the following query filter document into the 
      :guilabel:`Filter` search bar and click :guilabel:`Apply`:

      .. code-block:: javascript

         { saleDate: { $gte: { $date: "2016-01-01T00:00-00:00" }, $lte: { $date: "2016-01-02T00:00-00:00" } } }

      This query filter returns all documents in the ``sample_supplies.sales`` 
      collection where ``saleDate`` is on or between January 1 and 2, 2016 
      UTC time.

   .. step:: Edit a document.

      To edit a document displayed in the query results, hover over the
      document and click on the pencil icon. In the document editor, you can:

      - Add a new field. 
      - Delete an existing field.
      - Edit a field's name, value, or type.
      - Revert a specific change.

      For detailed instructions, see :atlas:`Create, View, Update, and Delete Documents 
      </atlas-ui/documents/#edit-one-document>`.

   .. step:: Save your changes.

      To confirm and save your changes, click the :guilabel:`Update` button.

Behavior
--------

Atomicity
~~~~~~~~~

All write operations in MongoDB are atomic on the level of a single
document. For more information on MongoDB and atomicity, see
:doc:`/core/write-operations-atomicity`.

``_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.

Field Order
~~~~~~~~~~~

.. include:: /includes/fact-update-field-order.rst

.. _write-operations-upsert-behavior:

Upsert Option
~~~~~~~~~~~~~

.. tabs-drivers::

   .. tab::
      :tabid: compass

      The upsert option is not available through |compass|.

   .. tab::
      :tabid: shell

      If :method:`~db.collection.updateOne()`,
      :method:`~db.collection.updateMany()`, or
      :method:`~db.collection.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.

   .. tab::
      :tabid: python

      If :py:meth:`~pymongo.collection.Collection.update_one`,
      :py:meth:`~pymongo.collection.Collection.update_many`, or
      :py:meth:`~pymongo.collection.Collection.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.

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

   .. tab::
      :tabid: motor
 
      If
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_one`,
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.update_many`,
      or
      :py:meth:`~motor.motor_asyncio.AsyncIOMotorCollection.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.

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

   .. tab::
      :tabid: java-sync

      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.

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

   .. tab::
      :tabid: java-async

      If the update and replace methods include the `UpdateOptions
      <https://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/UpdateOptions.html>`_
      parameter that specifies `UpdateOptions.upsert(true)
      <http://mongodb.github.io/mongo-java-driver/3.4/javadoc/com/mongodb/client/model/UpdateOptions.html?_ga=2.189375400.2069485991.1506612687-1453986945.1494866912&_gac=1.246606128.1506106401.EAIaIQobChMI3tmcxbu51gIVUrnACh12qwkREAAYASABEgLH4PD_BwE#upsert-boolean->`_
      **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.

   .. tab::
      :tabid: kotlin-coroutine

      If the update and replace methods include the
      `com.mongodb.client.model.UpdateOptions
      <{+java-api-docs+}/mongodb-driver-core/com/mongodb/client/model/UpdateOptions.html>`__
      parameter that specifies ``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.

   .. tab::
      :tabid: nodejs

      If :node-api:`updateOne() <Collection.html#updateOne>`,
      :node-api:`updateMany() <Collection.html#updateMany>`, or
      :node-api:`replaceOne() <Collection.html#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.

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

   .. tab::
      :tabid: php

      If :phpmethod:`updateOne()
      <phpmethod.MongoDB\\Collection::updateOne()>`,
      :phpmethod:`updateMany()
      <phpmethod.MongoDB\\Collection::updateMany()>`, or
      :phpmethod:`replaceOne()
      <phpmethod.MongoDB\\Collection::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.

   .. tab::
      :tabid: perl

      If :perl-api:`update_one()<Collection#update_one>`,
      :perl-api:`update_many()<Collection#update_many>`, or
      :perl-api:`replace_one()<Collection#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.

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

   .. tab::
      :tabid: ruby

      If
      :ruby-api:`update_one()<Collection.html#update_one-instance_method>`,
      :ruby-api:`update_many()<Collection.html#update_many-instance_method>`,
      or
      :ruby-api:`replace_one()<Collection.html#replace_one-instance_method>`
      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.

   .. tab::
      :tabid: scala

      If
      :scala-api:`updateOne()<updateOne(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`,
      :scala-api:`updateMany()<updateMany(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`,
      or
      :scala-api:`replaceOne()<replaceOne(filter:org.mongodb.scala.bson.conversions.Bson,replacement:TResult,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`
      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.

   .. tab::
      :tabid: csharp

      If :csharp-api:`UpdateOne()
      <M_MongoDB_Driver_IMongoCollection_1_UpdateOne>`,
      :csharp-api:`UpdateMany()
      <M_MongoDB_Driver_IMongoCollection_1_UpdateMany>`, or
      :csharp-api:`ReplaceOne()
      <M_MongoDB_Driver_IMongoCollection_1_ReplaceOne>` includes an
      :csharp-api:`UpdateOptions <T_MongoDB_Driver_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.

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

   .. tab::
      :tabid: go

      If :go-api:`Collection.UpdateOne<mongo#Collection.UpdateOne>`
      includes the :go-api:`Upsert option set to true
      <mongo/options#UpdateOptions>` **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 acknowledgment
requested from MongoDB for write operations. For details, see
:doc:`/reference/write-concern`.

.. tabs-drivers::

   .. tab::
      :tabid: shell

      .. seealso::

         - :doc:`/tutorial/update-documents-with-aggregation-pipeline`
            
         - :method:`db.collection.updateOne()`

         - :method:`db.collection.updateMany()`

         - :method:`db.collection.replaceOne()`

         - :ref:`additional-updates`

   .. tab::
      :tabid: compass

      .. seealso::

         - :compass:`Compass Documents </documents/>`

         - :ref:`Compass Query Bar <compass-query-bar>`

   .. tab::
      :tabid: python

      .. seealso::

         - :py:meth:`pymongo.collection.Collection.update_one`

         - :py:meth:`pymongo.collection.Collection.update_many`

         - :py:meth:`pymongo.collection.Collection.replace_one`

         - :ref:`additional-updates`

   .. tab::
      :tabid: motor

      .. seealso::

         - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_one`

         - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.update_many`

         - :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.replace_one`

         - :ref:`additional-updates`

   .. tab::
      :tabid: java-sync

      .. seealso::

         - com.mongodb.client.MongoCollection.updateOne_

         - com.mongodb.client.MongoCollection.updateMany_

         - com.mongodb.client.MongoCollection.replaceOne_

         - `Additional Java Synchronous Driver Write Examples`_

   .. tab::
      :tabid: java-async

      .. seealso::

         - `com.mongodb.reactivestreams.client.MongoCollection.updateOne
           <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateOne(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_

         - `com.mongodb.reactivestreams.client.MongoCollection.updateMany
           <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#updateMany(org.bson.conversions.Bson,%20org.bson.conversions.Bson)>`_

         - `com.mongodb.reactivestreams.client.MongoCollection.replaceOne
           <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#replaceOne(org.bson.conversions.Bson,%20TDocument)>`_

         - `Java Reactive Streams Driver Quick Tour <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/getting-started/quick-tour/>`_

   .. tab::
      :tabid: kotlin-coroutine

      .. seealso::

         - `MongoCollection.updateOne() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-one.html>`__
         - `MongoCollection.updateMany() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/update-many.html>`__
         - `MongoCollection.replaceOne() <{+java-api-docs+}/mongodb-driver-kotlin-coroutine/mongodb-driver-kotlin-coroutine/com.mongodb.kotlin.client.coroutine/-mongo-collection/replace-one.html>`__

         - :driver:`Kotlin Coroutine Driver Modify Documents Guide </kotlin/coroutine/current/fundamentals/crud/write-operations/modify/>`

   .. tab::
      :tabid: nodejs

      .. seealso::

         - :node-api:`Collection.updateOne() <Collection.html#updateOne>`

         - :node-api:`Collection.updateMany() <Collection.html#updateMany>`

         - :node-api:`Collection.replaceOne() <Collection.html#replaceOne>`

         - :ref:`additional-updates`

   .. tab::
      :tabid: php

      .. seealso::

         - :phpmethod:`MongoDB\\Collection::updateOne() <phpmethod.MongoDB\\Collection::updateOne()>`

         - :phpmethod:`MongoDB\\Collection::updateMany() <phpmethod.MongoDB\\Collection::updateMany()>`

         - :phpmethod:`MongoDB\\Collection::replaceOne() <phpmethod.MongoDB\\Collection::replaceOne()>`

         - :ref:`additional-updates`

   .. tab::
      :tabid: perl

      .. seealso::

         - :perl-api:`MongoDB::Collection::update_one()<Collection#update_one>`

         - :perl-api:`MongoDB::Collection::update_many()<Collection#update_many>`

         - :perl-api:`MongoDB::Collection::replace_one()<Collection#replace_one>`

         - :ref:`additional-updates`

   .. tab::
      :tabid: ruby

      .. seealso::

         - :ruby-api:`Mongo::Collection#update_one()<Collection.html#update_one-instance_method>`

         - :ruby-api:`Mongo::Collection#update_many()<Collection.html#update_many-instance_method>`

         - :ruby-api:`Mongo::Collection#replace_one()<Collection.html#replace_one-instance_method>`

   .. tab::
      :tabid: scala

      .. seealso::

         - :scala-api:`collection.updateOne()<updateOne(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

         - :scala-api:`collection.updateMany()<updateMany(filter:org.mongodb.scala.bson.conversions.Bson,update:org.mongodb.scala.bson.conversions.Bson,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

         - :scala-api:`collection.replaceOne()<replaceOne(filter:org.mongodb.scala.bson.conversions.Bson,replacement:TResult,options:org.mongodb.scala.model.UpdateOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.result.UpdateResult]>`

         - :ref:`additional-updates`

   .. tab::
      :tabid: csharp

      .. seealso::

         - :csharp-api:`IMongoCollection.UpdateOne() <M_MongoDB_Driver_IMongoCollection_1_UpdateOne>`

         - :csharp-api:`IMongoCollection.UpdateMany() <M_MongoDB_Driver_IMongoCollection_1_UpdateMany>`

         - :csharp-api:`IMongoCollection.ReplaceOne() <M_MongoDB_Driver_IMongoCollection_1_ReplaceOne>`

         - :ref:`additional-updates`

   .. tab::
      :tabid: go

      .. seealso::

         - :go-api:`Collection.UpdateOne<mongo#Collection.UpdateOne>`

         - :go-api:`Collection.UpdateMany<mongo#Collection.UpdateMany>`

         - :go-api:`Collection.ReplaceOne <mongo#Collection.ReplaceOne>`

         - :ref:`additional-updates`

.. toctree::
   :titlesonly:
   :hidden:

   /tutorial/update-documents-with-aggregation-pipeline
   /reference/update-methods