This beginner’s tutorial will explain to you how to use the $inc operator in MongoDB.
The $inc operator in MongoDB allows users to increment or add a value of a given field by a given value. This operator accepts both positive and negative values for addition. Moreover, if a given field does not exist, then the $inc operator creates the field and attaches the specified value to it. when a null value is provided, the operator throws an error.
If the user passes an empty operand expression like so: { }, then this operator will no longer throw an error (starting from MongoDB 5.0). The update operation is thus no-op.
This guide will provide you with multiple examples of how to use the $inc operator for your application. Let us get this quick guide started!
Table of Contents
The $inc Operator Syntax in MongoDB
Let us take a quick look at the $inc operator syntax when used in the mongo shell:
{ $inc: { field1: amount1, field2: amount2, ... } }
Using the $inc Operator in MongoDB
Let us get started with a bunch of examples that I would like to offer to explain the usage of this operator.
Let us take a look at our available documents inside the cats collection in the petShop database:
> db.cats.find().pretty()
{
"_id" : ObjectId("602eb6c728ff814b64eb3411"),
"name" : "Stephanie",
"age" : 18,
"breed" : "Persian",
"personality" : {
"dogFriendly" : true,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb73728ff814b64eb3412"),
"name" : "Whiskers",
"age" : 3,
"breed" : "Scottish Fold",
"personality" : {
"dogFriendly" : false,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb84628ff814b64eb3413"),
"name" : "Krissy",
"age" : 5,
"breed" : "Turkish Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc5ea78db75e09057cd0"),
"name" : "Cassy",
"age" : 15,
"breed" : "Japanese Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc9da78db75e09057cd1"),
"name" : "Shane",
"age" : 10,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebed7a78db75e09057cd2"),
"name" : "Phoebe",
"age" : 20,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
We have 6 cats documents in our collection now.
Incrementing Values with a Positive Value Using the $inc Operator
In this section, I will cover an example of using the $inc operator in MongoDB using a positive increment value on a field.
Let’s suppose we forget to update the age of the cats at our shop.
> db.cats.updateMany(
... { },
... { $inc: { age: 3 } }
... )
{ "acknowledged" : true, "matchedCount" : 6, "modifiedCount" : 6 }
> db.cats.find().pretty()
{
"_id" : ObjectId("602eb6c728ff814b64eb3411"),
"name" : "Stephanie",
"age" : 21,
"breed" : "Persian",
"personality" : {
"dogFriendly" : true,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb73728ff814b64eb3412"),
"name" : "Whiskers",
"age" : 6,
"breed" : "Scottish Fold",
"personality" : {
"dogFriendly" : false,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb84628ff814b64eb3413"),
"name" : "Krissy",
"age" : 8,
"breed" : "Turkish Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc5ea78db75e09057cd0"),
"name" : "Cassy",
"age" : 18,
"breed" : "Japanese Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc9da78db75e09057cd1"),
"name" : "Shane",
"age" : 13,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebed7a78db75e09057cd2"),
"name" : "Phoebe",
"age" : 23,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
We have successfully increased the age of all our cats by 3.
Incrementing with a Negative Value Using the $inc Operator in MongoDB
We will now use the $linc operator with a negative value which will decrement the values of our fields.
> db.cats.updateMany(
... { },
... { $inc: { age: -2 } }
... )
{ "acknowledged" : true, "matchedCount" : 6, "modifiedCount" : 6 }
> db.cats.find().pretty()
{
"_id" : ObjectId("602eb6c728ff814b64eb3411"),
"name" : "Stephanie",
"age" : 19,
"breed" : "Persian",
"personality" : {
"dogFriendly" : true,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb73728ff814b64eb3412"),
"name" : "Whiskers",
"age" : 4,
"breed" : "Scottish Fold",
"personality" : {
"dogFriendly" : false,
"childFriendly" : true
}
}
{
"_id" : ObjectId("602eb84628ff814b64eb3413"),
"name" : "Krissy",
"age" : 6,
"breed" : "Turkish Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc5ea78db75e09057cd0"),
"name" : "Cassy",
"age" : 16,
"breed" : "Japanese Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebc9da78db75e09057cd1"),
"name" : "Shane",
"age" : 11,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
{
"_id" : ObjectId("602ebed7a78db75e09057cd2"),
"name" : "Phoebe",
"age" : 21,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
}
}
Perfect! The values are now decremented.
Passing a Missing Nested Field to the $inc Operator in MongoDB
Let us now supply the $inc operator with a field that is not only missing but also is nested to see what happens.
Let’s say we want to add a price field that is nested inside the moreDetails field and set a value for each of them:
> db.cats.updateMany(
... { },
... { $inc: { "moreDetails.cost": 20000 } }
... )
{ "acknowledged" : true, "matchedCount" : 6, "modifiedCount" : 6 }
> db.cats.find().pretty()
{
"_id" : ObjectId("602eb6c728ff814b64eb3411"),
"name" : "Stephanie",
"age" : 19,
"breed" : "Persian",
"personality" : {
"dogFriendly" : true,
"childFriendly" : true
},
"moreDetails" : {
"cost" : 20000
}
}
{
"_id" : ObjectId("602eb73728ff814b64eb3412"),
"name" : "Whiskers",
"age" : 4,
"breed" : "Scottish Fold",
"personality" : {
"dogFriendly" : false,
"childFriendly" : true
},
"moreDetails" : {
"cost" : 20000
}
}
{
"_id" : ObjectId("602eb84628ff814b64eb3413"),
"name" : "Krissy",
"age" : 6,
"breed" : "Turkish Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
},
"moreDetails" : {
"cost" : 20000
}
}
{
"_id" : ObjectId("602ebc5ea78db75e09057cd0"),
"name" : "Cassy",
"age" : 16,
"breed" : "Japanese Angora",
"personality" : {
"dogFriendly" : true,
"childFriendly" : false
},
"moreDetails" : {
"cost" : 20000
}
}
{
"_id" : ObjectId("602ebc9da78db75e09057cd1"),
"name" : "Shane",
"age" : 11,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
},
"moreDetails" : {
"cost" : 20000
}
}
{
"_id" : ObjectId("602ebed7a78db75e09057cd2"),
"name" : "Phoebe",
"age" : 21,
"breed" : "Bobtail",
"personality" : {
"dogFriendly" : false,
"childFriendly" : false
},
"moreDetails" : {
"cost" : 20000
}
}
Perfect! We now have a moreDetails field with a nested price field in each of the documents and they have a value of 20000.
Read More: Listing All Collections, Databases, and Users in the MongoDB Shell [Easy Guide]
Conclusion
In this article, we learned to use the $inc operator in MongoDB with the above examples. Follow codeForGeek.com for more tutorials.