db.collection.updateOne.txt

=========================
db.collection.updateOne()
=========================

.. meta::
   :description: Update a single document that matches a specified filter.

.. facet::
   :name: programming_language 
   :values: shell

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

.. include:: includes/wayfinding/mongosh-method-updateOne.rst

Definition
----------

.. method:: db.collection.updateOne(filter, update, options)

   .. |dbcommand| replace:: :dbcommand:`update` command

   Updates a single document within the collection based on the filter.

Compatibility
-------------

.. |operator-method| replace:: ``db.collection.updateOne()``

This method is available in deployments hosted in the following environments:

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

Syntax
------

The :method:`~db.collection.updateOne()` method has the following syntax:

.. code-block:: javascript

   db.collection.updateOne(
      <filter>,
      <update>,
      {
        upsert: <boolean>,
        writeConcern: <document>,
        collation: <document>,
        arrayFilters: [ <filterdocument1>, ... ],
        hint:  <document|string>,
        let: <document>,
        sort: <document>
      }
   )

Parameters
~~~~~~~~~~

The :method:`db.collection.updateOne()` method takes the following
parameters:

.. list-table::
   :header-rows: 1
   :widths: 20 20 80

   * - Parameter

     - Type

     - Description

   * - :ref:`filter <update-one-filter>`

     - document

     - .. _update-one-filter:
       
       The selection criteria for the update. The same :ref:`query
       selectors <query-selectors>` as in the :method:`find()
       <db.collection.find()>` method are available.
       
       Specify an empty document ``{ }`` to update the first document returned in 
       the collection.

   * - :ref:`update <update-one-update>`

     - document or pipeline

     - .. _update-one-update:
     
       The modifications to apply. Can be one of the following:

       .. list-table::
          :widths: 40 80
          :class: border-table

          * - :ref:`Update document <update-one-method-update-document>`

            - .. _update-one-method-update-document:

              Contains only :ref:`update operator expressions
              <update-operators>`.
              
              For more information, see
              :ref:`updateOne-behavior-update-expressions`

          * - :ref:`Aggregation pipeline <update-one-method-agg-pipeline>`

            - .. _update-one-method-agg-pipeline:

              Contains only the following aggregation stages:

              .. include:: /includes/list-update-agg-stages.rst
       
              For more information, see
              :ref:`updateOne-behavior-aggregation-pipeline`.
       
       To update with a replacement document, see
       :method:`db.collection.replaceOne()`.

   * - ``upsert``

     - boolean

     - .. include:: /includes/extracts/updateOne-behavior-method.rst

   * - ``writeConcern``

     - document

     - Optional. A document expressing the :doc:`write concern
       </reference/write-concern>`. Omit to use the default write concern.
       
       .. include:: /includes/extracts/transactions-operations-write-concern.rst

   * - ``collation``

     - document

     - Optional. 
       
       .. include:: /includes/extracts/collation-option.rst

   * - ``arrayFilters``

     - array

     - Optional. An array of filter documents that determine which array elements to
       modify for an update operation on an array field.
       
       .. include::  /includes/extracts/arrayFilters-details.rst

       For examples, see :ref:`updateOne-arrayFilters`.

   * - :ref:`hint <update-one-hint>` 

     - Document or string

     - .. _update-one-hint:

       Optional. A document or string that specifies the :ref:`index
       <indexes>` to use to support the :ref:`query predicate
       <update-one-filter>`.
       
       The option can take an index specification document or the index
       name string.
       
       If you specify an index that does not exist, the operation
       errors.

       For an example, see :ref:`ex-update-one-hint`.

   * - ``let``
     
     - Document

     - .. _updateOne-let-syntax:
     
       Optional.

       .. include:: /includes/let-variables-syntax.rst
 
       .. include:: /includes/let-variables-syntax-note.rst

       For a complete example using ``let`` and variables,
       see :ref:`updateMany-let-example`.

   * - ``sort``
     - Document
     - .. _updateOne-document-syntax:

       Optional.

       Determines which document the operation updates if the query
       selects multiple documents. ``updateOne`` updates
       the first document in the sort order specified by this argument.

       .. include:: /includes/fact-sort-document-type.rst
       
       .. include:: /includes/fact-sort-consistency.rst

       See :ref:`sort-cursor-consistent-sorting` for more information.

       .. versionadded:: 8.0

Returns
~~~~~~~

The method returns a document that contains:

- ``matchedCount`` containing the number of matched documents

- ``modifiedCount`` containing the number of modified documents

- ``upsertedId`` containing the ``_id`` for the upserted document

- ``upsertedCount`` containing the number of upserted documents

- A boolean ``acknowledged`` as ``true`` if the operation ran with
  :term:`write concern` or ``false`` if write concern was disabled

Access Control
--------------

On deployments running with :setting:`~security.authorization`, the
user must have access that includes the following privileges:

- :authaction:`update` action on the specified collection(s).

- :authaction:`find` action on the specified collection(s).

- :authaction:`insert` action on the specified collection(s) if the
  operation results in an upsert.

The built-in role :authrole:`readWrite` provides the required
privileges.

.. _updateOne-behavior:

Behavior
--------

Updates a Single Document
~~~~~~~~~~~~~~~~~~~~~~~~~

:method:`db.collection.updateOne()` finds the first document that
matches the :ref:`filter <update-one-filter>` and applies the specified
:ref:`update <update-one-update>` modifications.

.. _updateOne-behavior-update-expressions:

Update with an Update Operator Expressions Document
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For the :ref:`update specifications <update-one-update>`, the
:method:`db.collection.updateOne()` method can accept a document that
only contains :ref:`update operator <update-operators>` expressions.

For example:

.. code-block:: javascript
   :emphasize-lines: 3
   :copyable: false

   db.collection.updateOne( 
      <query>,
      { $set: { status: "D" }, $inc: { quantity: 2 } },
      ...
   )

.. _updateOne-behavior-aggregation-pipeline:

Update with an Aggregation Pipeline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :method:`db.collection.updateOne()` method can accept an 
:ref:`aggregation pipeline <aggregation-pipeline>` 
``[ <stage1>, <stage2>, ... ]`` that specifies the modifications to perform. 
The pipeline can consist of the following stages:

.. include:: /includes/list-update-agg-stages.rst

Using the aggregation pipeline allows for a more expressive update
statement, such as expressing conditional updates based on current
field values or updating one field using the value of another field(s).

For example:

.. code-block:: javascript
   :emphasize-lines: 3-6
   :copyable: false

   db.collection.updateOne( 
      <query>,
      [ 
         { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ] } }, 
         { $unset: [ "misc1", "misc2" ] } 
      ]
      ...
   )

.. note::

   The ``$set`` and ``$unset`` used in the pipeline refers to the
   aggregation stages :pipeline:`$set` and :pipeline:`$unset`
   respectively, and not the update operators :update:`$set` and :update:`$unset`.

For examples, see :ref:`updateOne-example-agg`.

Upsert
~~~~~~

- .. include:: /includes/fact-7-1-sharded-upsert.rst

- If ``upsert: true`` and no documents match the ``filter``, 
  :method:`db.collection.updateOne()` creates a new 
  document based on the ``filter`` criteria and ``update`` 
  modifications. See :ref:`updateOne-example-update-with-upsert`.
  
- For additional :method:`db.collection.updateOne()` behavior on a 
  sharded collection, see :ref:`updateOne-sharded-collection`.

.. _updateOne-capped-collection:

Capped Collection
~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/capped-collection-immutable-document-size-update.rst

.. _updateOne-sharded-collection:

Sharded Collections
~~~~~~~~~~~~~~~~~~~

.. _updateOne-sharded-upsert:

``upsert`` on a Sharded Collection
``````````````````````````````````

To use :method:`db.collection.updateOne()` on a sharded collection:

- .. include:: /includes/fact-7-1-sharded-upsert.rst

- If you don't specify ``upsert: true``, you must include an exact
  match on the ``_id`` field or target a single shard (such as by
  including the shard key in the :ref:`filter <update-one-filter>`).

.. include:: /includes/extracts/missing-shard-key-equality-condition-update.rst

.. _updateOne-shard-key-modification:

Shard Key Modification
``````````````````````

.. include:: /includes/limits-sharding-shardkey-document-immutable.rst

.. include:: /includes/shard-key-modification-warning.rst

To modify the **existing** shard key value with
:method:`db.collection.updateOne()`:

- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not`
  issue the operation directly on the shard.

- You :red:`must` run either in a :doc:`transaction
  </core/transactions>` or as a :doc:`retryable write
  </core/retryable-writes>`. 

- You :red:`must` include an equality :ref:`filter
  <update-one-filter>` on the full shard key.

See also :ref:`updateOne-sharded-upsert`.

.. _updateOne-missing-shard-key:

Missing Shard Key
`````````````````

- Starting in version 7.1, you do not need to provide the :term:`shard key` 
  or ``_id`` field in the query specification. 

- Documents in a sharded collection can be
  :ref:`missing the shard key fields <shard-key-missing>`. To use
  :method:`db.collection.updateOne()` to set a **missing** shard key, 
  you :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` issue 
  the operation directly on the shard.

  In addition, the following requirements also apply:

  .. list-table::
     :header-rows: 1
     :widths: 30 70

     * - Task

       - Requirements

     * - To set to ``null``

       - Requires equality filter on the full shard key if
         ``upsert: true``.

     * - To set to a non-``null`` value

       - :red:`Must` be performed either inside a
         :ref:`transaction <transactions>` or as a
         :ref:`retryable write <retryable-writes>`.

         Requires equality filter on the full shard key if ``upsert: true``.

  .. tip::

     .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst

See also:

- :ref:`updateOne-sharded-upsert`

- :ref:`shard-key-missing`

Explainability
~~~~~~~~~~~~~~

:method:`~db.collection.updateOne()` is not compatible with
:method:`db.collection.explain()`.

Transactions
~~~~~~~~~~~~

.. include:: /includes/extracts/transactions-supported-operation.rst

.. include:: /includes/extracts/transactions-usage.rst

Upsert within Transactions
``````````````````````````

.. include:: /includes/extracts/transactions-upsert-availability.rst

Write Concerns and Transactions
````````````````````````````````

.. include:: /includes/extracts/transactions-operations-write-concern.rst

.. |operation| replace:: :method:`db.collection.updateOne()`

Oplog Entries
~~~~~~~~~~~~~

If a ``db.collection.updateOne()`` operation successfully updates a
document, the operation adds an entry on the :term:`oplog` (operations
log). If the operation fails or does not find a document to update, the
operation does not add an entry on the oplog. 

.. _updateOne-method-examples:

Examples
--------

.. _updateOne-example-update:

Update using Update Operator Expressions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``restaurant`` collection contains the  following documents:

.. code-block:: javascript

   { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan" },
   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
   { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 0 }

The following operation updates a single document where 
``name: "Central Perk Cafe"`` with the ``violations`` field:

.. code-block:: javascript

   try {
      db.restaurant.updateOne( 
         { "name" : "Central Perk Cafe" }, 
         { $set: { "violations" : 3 } } 
      );
   } catch (e) {
      print(e);
   }
  
The operation returns:

.. code-block:: javascript

   { "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

If no matches were found, the operation instead returns:

.. code-block:: javascript

   { "acknowledged" : true, "matchedCount" : 0, "modifiedCount" : 0 }

Setting ``upsert: true`` would insert the document if no match was found. See 
:ref:`updateOne-example-update-with-upsert`

.. _updateOne-example-agg:

Update with Aggregation Pipeline
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :method:`db.collection.updateOne()` can use an aggregation pipeline for the 
update. The pipeline can consist of the following stages:

.. include:: /includes/list-update-agg-stages.rst

Using the aggregation pipeline allows for a more expressive update
statement, such as expressing conditional updates based on current
field values or updating one field using the value of another field(s).

Example 1
`````````

The following examples uses the aggregation pipeline to modify a field
using the values of the other fields in the document.

Create a ``students`` collection with the following documents:

.. code-block:: javascript

   db.students.insertMany( [
      { "_id" : 1, "student" : "Skye", "points" : 75, "commentsSemester1" : "great at math", "commentsSemester2" : "loses temper", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") },
      { "_id" : 2, "student" : "Elizabeth", "points" : 60, "commentsSemester1" : "well behaved", "commentsSemester2" : "needs improvement", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
   ] )

Assume that instead of separate ``commentsSemester1`` and ``commentsSemester2`` 
fields in the first document, you want to gather these into a ``comments`` field,
like the second document. The following update operation uses an
aggregation pipeline to:

- add the new ``comments`` field and set the ``lastUpdate`` field.

- remove the ``commentsSemester1`` and ``commentsSemester2`` fields for all 
  documents in the collection.

Make sure that the filter in the update command targets a unique document. The
field ``id`` in the code below is an example of such a filter: 

.. code-block:: javascript

   db.students.updateOne(
      { _id: 1 },
      [
         { $set: { status: "Modified", comments: [ "$commentsSemester1", "$commentsSemester2" ], lastUpdate: "$$NOW" } },
         { $unset: [ "commentsSemester1", "commentsSemester2" ] }
      ]
   )

.. note::

   The ``$set`` and ``$unset`` used in the pipeline refers to the
   aggregation stages :pipeline:`$set` and :pipeline:`$unset`
   respectively, and not the update operators :update:`$set` and :update:`$unset`.

First Stage
   The :pipeline:`$set` stage:
   
   - creates a new array field ``comments`` whose elements are the current
     content of the ``misc1`` and ``misc2`` fields and 

   - sets the field ``lastUpdate`` to the value of the aggregation
     variable :variable:`NOW`. The aggregation variable
     :variable:`NOW` resolves to the current datetime value and remains
     the same throughout the pipeline. To access aggregation
     variables, prefix the variable with double dollar signs ``$$``
     and enclose in quotes.
   

Second Stage
   The :pipeline:`$unset` stage removes the ``commentsSemester1`` and 
   ``commentsSemester2`` fields.

After the command, the collection contains the following documents:

.. code-block:: javascript
   :copyable: false

   { "_id" : 2, "student" : "Elizabeth", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "well behaved", "needs improvement" ] }
   { _id: 1, student: 'Skye', points: 75, commentsSemester1: 'great at math', commentsSemester2: 'loses temper', lastUpdate: ISODate("2019-01-01T00:00:00.000Z") }

Note that after introducing a sort, only the first document encountered in the 
sort order is modified and the remaining documents are left untouched. 

Example 2
`````````

The aggregation pipeline allows the update to perform conditional
updates based on the current field values as well as use current field
values to calculate a separate field value.

For example, create a ``students3`` collection with the following documents:

.. code-block:: javascript

   db.students3.insertMany( [
      { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
      { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") },
      { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }
   ] )

The third document ``_id: 3`` is missing the ``average`` and ``grade``
fields. Using an aggregation pipeline, you can update the document with
the calculated grade average and letter grade.

.. code-block:: javascript

   db.students3.updateOne(
      { _id: 3 },
      [
        { $set: { average: { $trunc: [  { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } },
        { $set: { grade: { $switch: {
                              branches: [
                                  { case: { $gte: [ "$average", 90 ] }, then: "A" },
                                  { case: { $gte: [ "$average", 80 ] }, then: "B" },
                                  { case: { $gte: [ "$average", 70 ] }, then: "C" },
                                  { case: { $gte: [ "$average", 60 ] }, then: "D" }
                              ],
                              default: "F"
        } } } }
      ]
   )

.. note::

   The ``$set`` used in the pipeline refers to the aggregation stage
   :pipeline:`$set`, and not the update operators :update:`$set`.

First Stage
   The :pipeline:`$set` stage:
   
   - calculates a new field ``average`` based on the average of the
     ``tests`` field. See :group:`$avg` for more information on the
     ``$avg`` aggregation operator and :expression:`$trunc` for more
     information on the ``$trunc`` truncate aggregation operator.
     
   - sets the field ``lastUpdate`` to the value of the aggregation
     variable :variable:`NOW`. The aggregation variable
     :variable:`NOW` resolves to the current datetime value and remains
     the same throughout the pipeline. To access aggregation
     variables, prefix the variable with double dollar signs ``$$``
     and enclose in quotes.

Second Stage
   The :pipeline:`$set` stage calculates a new field ``grade`` based on
   the ``average`` field calculated in the previous stage. See
   :expression:`$switch` for more information on the ``$switch``
   aggregation operator.

After the command, the collection contains the following documents:

.. code-block:: javascript

   { "_id" : 1, "tests" : [ 95, 92, 90 ], "average" : 92, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
   { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") }
   { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" }

.. seealso::

   :doc:`/tutorial/update-documents-with-aggregation-pipeline`

.. _updateOne-example-update-with-upsert:

Update with Upsert
~~~~~~~~~~~~~~~~~~

The ``restaurant`` collection contains the following documents:

.. code-block:: javascript

   { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
   { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : "0" }

The following operation attempts to update the document with 
``name : "Pizza Rat's Pizzaria"``, while ``upsert: true`` :

.. code-block:: javascript

   try {
      db.restaurant.updateOne( 
         { "name" : "Pizza Rat's Pizzaria" },
         { $set: {"_id" : 4, "violations" : 7, "borough" : "Manhattan" } }, 
         { upsert: true }
      );
   } catch (e) {
      print(e);
   }

Since ``upsert:true`` the document is ``inserted`` based on the ``filter`` and 
``update`` criteria. The operation returns:

.. code-block:: javascript

   {
      "acknowledged" : true,
      "matchedCount" : 0,
      "modifiedCount" : 0,
      "upsertedId" : 4,
      "upsertedCount": 1
   }

The collection now contains the following documents:

.. code-block:: javascript

   { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
   { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
   { "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "violations" : 7 }

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

.. code-block:: javascript

   try {
      db.restaurant.updateOne( 
         { "violations" : { $gt: 10} }, 
         { $set: { "Closed" : true } }, 
         { upsert: true }
      );
   } catch (e) {
      print(e);
   }

The operation returns:

.. code-block:: javascript

   {
      "acknowledged" : true,
      "matchedCount" : 0,
      "modifiedCount" : 0,
      "upsertedId" : ObjectId("56310c3c0c5cbb6031cafaea")
   }

The collection now contains the following documents:

.. code-block:: javascript

   { "_id" : 1, "name" : "Central Perk Cafe", "Borough" : "Manhattan", "violations" : 3 },
   { "_id" : 2, "name" : "Rock A Feller Bar and Grill", "Borough" : "Queens", "violations" : 2 },
   { "_id" : 3, "name" : "Empire State Pub", "Borough" : "Brooklyn", "violations" : 4 },
   { "_id" : 4, "name" : "Pizza Rat's Pizzaria", "Borough" : "Manhattan", "grade" : 7 }
   { "_id" : ObjectId("56310c3c0c5cbb6031cafaea"), "Closed" : true }

Since no documents matched the filter, and ``upsert`` was ``true``, 
:method:`~db.collection.updateOne` inserted the document with a generated 
``_id`` and the ``update`` criteria only.

.. _updateOne-example-update-with-write-concern:

Update with Write Concern
~~~~~~~~~~~~~~~~~~~~~~~~~

Given a three member replica set, the following operation specifies a 
``w`` of ``majority``, ``wtimeout`` of ``100``:

.. code-block:: javascript

   try {
      db.restaurant.updateOne(
          { "name" : "Pizza Rat's Pizzaria" },
          { $inc: { "violations" : 3}, $set: { "Closed" : true } },
          { w: "majority", wtimeout: 100 }
      );
   } catch (e) {
      print(e);
   }

If the primary and at least one secondary acknowledge each write operation 
within 100 milliseconds, it returns:

.. code-block:: javascript

   { "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

If the acknowledgment takes longer than the ``wtimeout`` limit, the following 
exception is thrown:

.. code-block:: javascript

   WriteConcernError({
      "code" : 64,
      "errmsg" : "waiting for replication timed out",
      "errInfo" : {
        "wtimeout" : true,
        "writeConcern" : {
          "w" : "majority",
          "wtimeout" : 100,
          "provenance" : "getLastErrorDefaults"
        }
      }
   })

The following table explains the possible values of
``errInfo.writeConcern.provenance``:

.. include:: /includes/fact-wc-provenance-table.rst

Update with Sort
~~~~~~~~~~~~~~~~

.. versionadded:: 8.0

The following example deactivates the lowest rated active user:

.. code-block:: javascript

   db.people.updateOne(
      { state: "active" },
      { $set: { state: "inactive" } },
      { sort: { rating: 1 }
   )

Specify Collation
~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/collation-versionadded.rst

A collection ``myColl`` has the following documents:

.. code-block:: javascript

   { _id: 1, category: "café", status: "A" }
   { _id: 2, category: "cafe", status: "a" }
   { _id: 3, category: "cafE", status: "a" }

The following operation includes the :ref:`collation <collation>`
option:

.. code-block:: javascript

   db.myColl.updateOne(
      { category: "cafe" },
      { $set: { status: "Updated" } },
      { collation: { locale: "fr", strength: 1 } }
   );

.. _updateOne-arrayFilters:

Specify ``arrayFilters`` for an Array Update Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/extracts/arrayFilters-blurb.rst

Update Elements Match ``arrayFilters`` Criteria
```````````````````````````````````````````````

Create a collection ``students`` with the following documents:

.. code-block:: javascript

   db.students.insertMany( [
      { "_id" : 1, "grades" : [ 95, 92, 90 ] },
      { "_id" : 2, "grades" : [ 98, 100, 102 ] },
      { "_id" : 3, "grades" : [ 95, 110, 100 ] }
   ] )

To modify all elements that are greater than or equal to ``100`` in the
``grades`` array, use the filtered positional operator
:update:`$[\<identifier\>]` with the ``arrayFilters`` option in the
:method:`db.collection.updateOne` method:

.. code-block:: javascript

   db.students.updateOne(
      { grades: { $gte: 100 } },
      { $set: { "grades.$[element]" : 100 } },
      { arrayFilters: [ { "element": { $gte: 100 } } ] }
   )

The operation updates the ``grades`` field of a single document, and
after the operation, the collection has the following documents:

.. code-block:: javascript
   :emphasize-lines: 2

   { "_id" : 1, "grades" : [ 95, 92, 90 ] }
   { "_id" : 2, "grades" : [ 98, 100, 100 ] }
   { "_id" : 3, "grades" : [ 95, 110, 100 ] }

Update Specific Elements of an Array of Documents
`````````````````````````````````````````````````

Create a collection ``students2`` with the following documents:

.. code-block:: javascript

   db.students2.insertMany( [
      {
         "_id" : 1,
         "grades" : [
            { "grade" : 80, "mean" : 75, "std" : 6 },
            { "grade" : 85, "mean" : 90, "std" : 4 },
            { "grade" : 85, "mean" : 85, "std" : 6 }
         ]
      },
      {
         "_id" : 2,
         "grades" : [
            { "grade" : 90, "mean" : 75, "std" : 6 },
            { "grade" : 87, "mean" : 90, "std" : 3 },
            { "grade" : 85, "mean" : 85, "std" : 4 }
         ]
      }
   ] )

To modify the value of the ``mean`` field for all elements in the
``grades`` array where the grade is greater than or equal to ``85``,
use the filtered positional operator :update:`$[\<identifier\>]` with
the ``arrayFilters`` in the :method:`db.collection.updateOne` method:

.. code-block:: javascript

   db.students2.updateOne(
      { },
      { $set: { "grades.$[elem].mean" : 100 } },
      { arrayFilters: [ { "elem.grade": { $gte: 85 } } ] }
   )

The operation updates the array of a single document, and after the
operation, the collection has the following documents:

.. code-block:: javascript
   :emphasize-lines: 5-6

   {
      "_id" : 1,
      "grades" : [
         { "grade" : 80, "mean" : 75, "std" : 6 },
         { "grade" : 85, "mean" : 100, "std" : 4 },
         { "grade" : 85, "mean" : 100, "std" : 6 } 
       ]
   }
   {
      "_id" : 2,
      "grades" : [
         { "grade" : 90, "mean" : 75, "std" : 6 },
         { "grade" : 87, "mean" : 90, "std" : 3 },
         { "grade" : 85, "mean" : 85, "std" : 4 }
      ]
   }

.. _ex-update-one-hint:

Specify ``hint`` for Update Operations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Create a sample ``students`` collection with the following documents:

.. code-block:: javascript

   db.students.insertMany( [
      { "_id" : 1, "student" : "Richard", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
      { "_id" : 2, "student" : "Jane", "grade" : "A", "points" : 60,  "comments1" : "well behaved", "comments2" : "fantastic student" },
      { "_id" : 3, "student" : "Ronan", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
      { "_id" : 4, "student" : "Noah", "grade" : "D", "points" : 20,  "comments1" : "needs improvement", "comments2" : null },
      { "_id" : 5, "student" : "Adam", "grade" : "F", "points" :  0,  "comments1" : null, "comments2" : null },
      { "_id" : 6, "student" : "Henry", "grade" : "A", "points" : 86,  "comments1" : "fantastic student", "comments2" : "well behaved" }
   ] )

Create the following indexes on the collection:

.. code-block:: javascript

   db.students.createIndex( { grade: 1 } )
   db.students.createIndex( { points: 1 } )

The following update operation explicitly hints to use the index ``{
grade: 1 }``:

.. note::

   If you specify an index that does not exist, the operation errors.

.. code-block:: javascript

   db.students.updateOne(
      { "points": { $lte: 20 }, "grade": "F" }, 
      { $set: { "comments1": "failed class" } },
      { hint: { grade: 1 } }
   )

The update command returns the following:

.. code-block:: javascript

   { "acknowledged" : true, "matchedCount" : 1, "modifiedCount" : 1 }

.. note::
   Even though 3 documents match the criteria of the update, ``updateOne`` only
   modifies the first document it finds. Therefore, even though the students 
   Richard, Ronan, and Adam all meet the criteria, only Richard will be updated. 

To see the index used, run :dbcommand:`explain` on the operation:

.. code-block:: javascript

   db.students.explain().update(
      { "points": { $lte: 20 }, "grade": "F" },
      { $set: { "comments1": "failed class" } },
      { multi: true, hint: { grade: 1 } }
   )

.. _updateOne-example-user-roles-system-variable:

User Roles and Document Updates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/user-roles-system-variable-update-example-introduction.rst

.. procedure::
   :style: normal

   .. step:: Log in as ``Michelle``

      .. include:: /includes/user-roles-system-variable-example-login-michelle.rst

   .. step:: Perform update
   
      .. include:: /includes/user-roles-system-variable-update-one-example.rst

.. include:: /includes/user-roles-system-variable-update-example-middle.rst

.. procedure::
   :style: normal

   .. step:: Log in as ``James``

      .. include:: /includes/user-roles-system-variable-example-login-james.rst

   .. step:: Attempt to perform update
   
      .. include:: /includes/user-roles-system-variable-update-one-example.rst

.. include:: /includes/user-roles-system-variable-update-example-end.rst

.. seealso::

   To update multiple documents, see
   :method:`db.collection.updateMany()`.