Docs Home → MongoDB Manual
On this page
- Definition
- Behavior
- Example
The $inc operator increments a field by a specified value and has the following form:
| { $inc: { : , : , ... } } |
To specify a in an embedded document or in an array, use dot notation.
Starting in MongoDB 5.0, update operators process document fields with string-based names in lexicographic order. Fields with numeric names are processed in numeric order. See Update Operators Behavior for details.
The $inc operator accepts positive and negative values.
If the field does not exist, $inc creates the field and sets the field to the specified value.
Use of the $inc operator on a field with a null value will generate an error.
$inc is an atomic operation within a single document.
Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $inc with an empty operand expression [ { } ]. An empty update results in no changes and no oplog entry is created [meaning that the operation is a no-op].
Create the products collection:
| db.products.insertOne[ |
| { |
| _id: 1, |
| sku: "abc123", |
| quantity: 10, |
| metrics: { orders: 2, ratings: 3.5 } |
| } |
| ] |
The following updateOne[] operation uses the $inc operator to:
- increase the "metrics.orders" field by 1
- increase the quantity field by -2 [which decreases quantity]
| db.products.updateOne[ |
| { sku: "abc123" }, |
| { $inc: { quantity: -2, "metrics.orders": 1 } } |
| ] |
The updated document would resemble:
| { |
| _id: 1, |
| sku: 'abc123', |
| quantity: 8, |
| metrics: { orders: 3, ratings: 3.5 } |
| } |
Tip
See also:
- db.collection.updateMany[]
- db.collection.findAndModify[]
| db.supplies.insertMany[[ |
| { "_id" : 1, "item" : "binder", "qty" : NumberInt["100"], "price" : NumberDecimal["12"] }, |
| { "_id" : 2, "item" : "notebook", "qty" : NumberInt["200"], "price" : NumberDecimal["8"] }, |
| { "_id" : 3, "item" : "pencil", "qty" : NumberInt["50"], "price" : NumberDecimal["6"] }, |
| { "_id" : 4, "item" : "eraser", "qty" : NumberInt["150"], "price" : NumberDecimal["3"] }, |
| { "_id" : 5, "item" : "legal pad", "qty" : NumberInt["42"], "price" : NumberDecimal["10"] } |
| ]] |
Docs Home → MongoDB Manual
Aggregation operations process multiple documents and return computed results. You can use aggregation operations to:
- Group values from multiple documents together.
- Perform operations on the grouped data to return a single result.
- Analyze data changes over time.
To perform aggregation operations, you can use:
An aggregation pipeline consists of one or more stages that process documents:
- Each stage performs an operation on the input documents. For example, a stage can filter documents, group documents, and calculate values.
- The documents that are output from a stage are passed to the next stage.
- An aggregation pipeline can return results for groups of documents. For example, return the total, average, maximum, and minimum values.
Starting in MongoDB 4.2, you can also update documents with an aggregation pipeline. See Updates with Aggregation Pipeline.
The following aggregation pipeline example contains two stages and returns the total order quantity of medium size pizzas grouped by pizza name:
| db.orders.aggregate[ [ |
| { |
| $match: { size: "medium" } |
| }, |
| { |
| $group: { _id: "$name", totalQuantity: { $sum: "$quantity" } } |
| } |
| ] ] |
The $match stage:
- Filters the pizza order documents to pizzas with a size of medium.
- Passes the remaining documents to the $group stage.
The $group stage:
- Groups the remaining documents by pizza name.
- Uses $sum to calculate the total order quantity for each pizza name. The total is stored in the totalQuantity field returned by the aggregation pipeline.
For runnable examples containing sample input documents, see Complete Aggregation Pipeline Examples.
You can use the following single purpose aggregation methods to aggregate documents from a single collection:
The single purpose aggregation methods are simple but lack the capabilities of an aggregation pipeline.
Starting in MongoDB 5.0, map-reduce is deprecated:
- Instead of map-reduce, you should use an aggregation pipeline. Aggregation pipelines provide better performance and usability than map-reduce.
- You can rewrite map-reduce operations using aggregation pipeline stages, such as $group, $merge, and others.
- For map-reduce operations that require custom functionality, you can use the $accumulator and $function aggregation operators, available starting in version 4.4. You can use those operators to define custom aggregation expressions in JavaScript.
For examples of aggregation pipeline alternatives to map-reduce, see:
- Map-Reduce to Aggregation Pipeline
- Map-Reduce Examples
For a feature comparison of aggregation pipelines and map-reduce, see Aggregation Commands Comparison.
To learn more about aggregations, see:
← Tailable CursorsAggregation Pipeline →