$addToSet
On this page
Definition
Compatibility
You can use $addToSet for deployments hosted in the following
environments:
MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud
MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB
Syntax
The $addToSet operator has the form:
{ $addToSet: { <field1>: <value1>, ... } }
To specify a <field> in an embedded document or in an array, use
dot notation.
Behavior
In MongoDB 4.4 and earlier, update operators process document fields in lexicographic order. See Update Operators Behavior for details.
$addToSet only ensures that there are no duplicate items
added to the set and does not affect existing duplicate elements.
$addToSet does not guarantee a particular ordering of
elements in the modified set.
Missing Field
If you use $addToSet on a field that is absent in the document to
update, $addToSet creates the array field with the specified
value as its element.
Field is Not an Array
If you use $addToSet on a field that is not an array, the
operation will fail. For example, consider a document in a collection
foo that contains a non-array field colors.
{ _id: 1, colors: "blue,green,red" }
The following $addToSet operation on the non-array field
colors fails:
db.foo.update( { _id: 1 }, { $addToSet: { colors: "c" } } )
Value to Add is An Array
If the value is an array, $addToSet appends the whole array
as a single element.
Consider a document in a collection test containing an array
field letters:
{ _id: 1, letters: ["a", "b"] }
The following operation appends the array [ "c", "d" ] to the
letters field:
db.test.update( { _id: 1 }, { $addToSet: { letters: [ "c", "d" ] } } )
The letters array now includes the [ "c", "d" ] array
as an element:
{ _id: 1, letters: [ "a", "b", [ "c", "d" ] ] }
Tip
To add each element of the value separately, use the
$each modifier with $addToSet. See
$each Modifier for details.
Value to Add is a Document
If the value is a document, MongoDB determines that the document is a duplicate if an existing document in the array matches the to-be-added document exactly; i.e. the existing document has the exact same fields and values and the fields are in the same order. As such, field order matters and you cannot specify that MongoDB compare only a subset of the fields in the document to determine whether the document is a duplicate of an existing array element.
Examples
Consider a collection inventory with the following document:
{ _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] }
Add to Array
The following operation adds the element "accessories" to the
tags array since "accessories" does not exist in the array:
db.inventory.update( { _id: 1 }, { $addToSet: { tags: "accessories" } } )
Value Already Exists
The following $addToSet operation has no effect as
"camera" is already an element of the tags array:
db.inventory.update( { _id: 1 }, { $addToSet: { tags: "camera" } } )
$each Modifier
You can use the $addToSet operator with the
$each modifier. The $each modifier allows the
$addToSet operator to add multiple values to the array
field.
A collection inventory has the following document:
{ _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }
Then the following operation uses the $addToSet operator
with the $each modifier to add multiple elements to the
tags array:
db.inventory.update( { _id: 2 }, { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } } )
The operation adds only "camera" and "accessories" to the
tags array since "electronics" already exists in the array:
{ _id: 2, item: "cable", tags: [ "electronics", "supplies", "camera", "accessories" ] }