Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

$addToSet

On this page

  • Definition
  • Compatibility
  • Syntax
  • Behavior
  • Examples
$addToSet

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

You can use $addToSet for deployments hosted in the following environments:

  • MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

The $addToSet operator has the form:

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

To specify a <field> 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.

$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.

Starting in MongoDB 5.0, mongod no longer raises an error when you use an update operator like $addToSet 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).

If you use $addToSet on a field that is absent from the document to update, $addToSet creates the array field with the specified value as its element.

If you use $addToSet on a field that is not an array, the operation will fail.

For example, create the pigments collection:

db.pigments.insertOne( { _id: 1, colors: "blue, green, red" } )

The colors field is not an array. The following $addToSet operation fails:

db.pigments.updateOne(
{ _id: 1 },
{ $addToSet: { colors: "mauve" } }
)

If the value is an array, $addToSet appends the whole array as a single element.

Create the alphabet collection:

db.alphabet.insertOne( { _id: 1, letters: ["a", "b"] } )

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

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

The array [ "c", "d" ] is added as a single 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.

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.

Create the inventory collection:

db.inventory.insertOne(
{ _id: 1, item: "polarizing_filter", tags: [ "electronics", "camera" ] }
)

The following operation adds the element "accessories" to the tags array since "accessories" does not exist in the array:

db.inventory.updateOne(
{ _id: 1 },
{ $addToSet: { tags: "accessories" } }
)

The following $addToSet operation has no effect because "camera" is already an element of the tags array:

db.inventory.updateOne(
{ _id: 1 },
{ $addToSet: { tags: "camera" } }
)

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.updateOne(
{ _id: 2 },
{ $addToSet: { tags: { $each: [ "camera", "electronics", "accessories" ] } } }
)

The operation only adds "camera" and "accessories" to the tags array. "electronics" was already in the array:

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

Tip

See also:

←  $[<identifier>]$pop →