diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt index b8390ceb4d0..7651f40083d 100644 --- a/source/reference/operator/update/inc.txt +++ b/source/reference/operator/update/inc.txt @@ -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: { : , ... } } + { $inc: { : , : , ... } } - 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``.