Skip to content

$inc operator and missing field behavior #1976

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

$inc operator and missing field behavior #1976

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 27 additions & 33 deletions source/reference/operator/update/inc.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,52 +4,46 @@ $inc

.. default-domain:: mongodb

Definition
----------

.. update:: $inc

The :update:`$inc` operator increments a value of a field by a
specified amount. If the field does not exist, :update:`$inc` adds
the field and sets the field to the specified amount.
:update:`$inc` accepts positive and negative incremental
amounts. Consider the following syntax:
The :update:`$inc` operator increments a field by a specified value and
has the following form:

.. code-block:: javascript

{ $inc: { <field1>: <amount1>, ... } }
{ $inc: { <field1>: <amount1>, <field2>: <amount2>, ... } }

The following example increments the value of ``quantity`` by ``5``
for the *first* matching document in the ``products`` collection
where ``sku`` equals ``abc123``:
Behavior
--------

.. code-block:: javascript
The :update:`$inc` operator accepts positive and negative values.

db.products.update( { sku: "abc123" },
{ $inc: { quantity: 5 } } )
If the field does not exist, :update:`$inc` adds the field to a document
and sets the field to the specified value.

To update all matching documents in the collection, specify
``multi:true`` option in the :method:`~db.collection.update()`
method. For example:
Use of the :update:`$inc` operator on a field with a null value will
generate an error.

.. code-block:: javascript
Examples
--------

db.records.update( { age: 20 }, { $inc: { age: 1 } }, { multi: true } );
The following :method:`~db.collection.update()` operation uses the
:update:`$inc` operator to decrease the ``quantity`` field and increase
the ``sales`` field for the *first* matching document in the ``products``
collection where ``sku`` equals ``abc123``.

The :method:`~db.collection.update()` operation increments the value
of the ``age`` field by ``1`` for all documents in the ``records``
collection that have an ``age`` field equal to ``20``.
.. code-block:: javascript

The :update:`$inc` operator can operate on multiple fields in a
document. The following :method:`~db.collection.update()` operation
uses the :update:`$inc` operator to modify both the ``quantity``
field and the ``sales`` field for the *first* matching document in
the ``products`` collection where ``sku`` equals ``abc123``:
db.products.update( { sku: "abc123" },
{ $inc: { quantity: -2, sales: 2 } } )

.. code-block:: javascript
The :update:`$inc` operator expression specifies ``-2`` for the
``quantity`` field to *decrease* the value of the ``quantity`` field (i.e.
increment by ``-2``) and specifies ``2`` for the ``sales`` field to
increase the value of the ``sales`` field by ``2``.

db.products.update( { sku: "abc123" },
{ $inc: { quantity: -2, sales: 2 } } )
See the :method:`~db.collection.update()` method for more information.

In the above example, the :update:`$inc` operator expression
specifies ``-2`` for the ``quantity`` field to *decrease* the value
of the ``quantity`` field (i.e. increment by ``-2``) and specifies
``2`` for the ``sales`` field to increase the value of the ``sales``
field by ``2``.