$addToSet

$addToSet

Definition

$addToSet
The $addToSet operator adds a value to an array unless the valueis already present, in which case $addToSet does nothing to thatarray.

The $addToSet operator has the form:

{ $addToSet: { <field1>: <value1>, ... } }

To specify a <field> in an embedded document or in an array, usedot notation.

Behavior

$addToSet only ensures that there are no duplicate itemsadded to the set and does not affect existing duplicate elements.$addToSet does not guarantee a particular ordering ofelements in the modified set.

Missing Field

If you use $addToSet on a field is absent in the document toupdate, $addToSet creates the array field with the specifiedvalue as its element.

Field is Not an Array

If you use $addToSet on a field that is not an array, theoperation will fail. For example, consider a document in a collectionfoo that contains a non-array field colors.

{ _id: 1, colors: "blue,green,red" }

The following $addToSet operation on the non-array fieldcolors 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 arrayas a single element.

Consider a document in a collection test containing an arrayfield letters:

{ _id: 1, letters: ["a", "b"] }

The following operation appends the array [ "c", "d" ] to theletters field:

db.test.update(
   { _id: 1 },
   { $addToSet: { letters: [ "c", "d" ] } }
)

The letters array now includes the [ "c", "d" ] arrayas 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 aduplicate if an existing document in the array matches the to-be-addeddocument exactly; i.e. the existing document has the exact same fieldsand values and the fields are in the same order. As such, field ordermatters and you cannot specify that MongoDB compare only a subset ofthe fields in the document to determine whether the document is aduplicate 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 thetags 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 arrayfield.

A collection inventory has the following document:

{ _id: 2, item: "cable", tags: [ "electronics", "supplies" ] }

Then the following operation uses the $addToSet operatorwith the $each modifier to add multiple elements to thetags array:

db.inventory.update(
   { _id: 2 },
   { $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
 )

The operation adds only "camera" and "accessories" to thetags array since "electronics" already exists in the array:

{
  _id: 2,
  item: "cable",
  tags: [ "electronics", "supplies", "camera", "accessories" ]
}