$addToSet

在本页

定义

兼容性
语法
行为
示例

定义

$addToSet: 该$addToSet 运算符将值添加到数组中，除非该值已存在，否则 $addToSet 对该数组不执行任何操作。

兼容性

您可以使用 $addToSet 对以下环境中的部署进行操作

MongoDB Atlas：MongoDB 在云中的完全托管服务

MongoDB 企业版：基于订阅的 MongoDB 自托管版本
MongoDB 社区版：MongoDB 的开源、免费使用和自托管版本

语法

$addToSet 操作符的格式为

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

要指定内嵌文档或数组中的 <字段>，请使用点表示法。

行为

从 MongoDB 5.0 开始，更新操作符按基于字符串名称的字典顺序处理文档字段。具有数字名称的字段按数字顺序处理。有关详细信息，请参阅更新操作符行为。

$addToSet 仅确保在集合中添加的元素没有重复，不会影响现有的重复元素。 $addToSet 不保证修改后集合中元素的具体排序。

从 MongoDB 5.0 开始，当使用 mongod 并使用一个空的操作符表达式（{ }）时，不再会抛出错误。空的更新不会导致任何更改，也不会创建 oplog 记录（意味着该操作是无效的）。

缺失字段

如果你在一个不存在的字段上使用 $addToSet，则 $addToSet 会创建一个数组字段，并用指定的值作为其元素。

字段不是数组

如果你在一个不是数组的字段上使用 $addToSet，则操作将失败。

例如，创建 pigments 集合

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

colors 字段不是数组。下面的 $addToSet 操作将失败

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

要添加的值是一个数组

如果值是一个数组，$addToSet 将整个数组追加为一个单个元素。

创建 alphabet 集合

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

以下操作将数组 [ "c", "d" ] 追加到 letters 字段

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

数组 [ "c", "d" ] 作为单个元素添加

{ _id: 1, letters: [ 'a', 'b', [ 'c', 'd' ] ] }

提示

要分别添加值的每个元素，请使用与 $each 修饰符结合的 $addToSet。有关详细信息，请参阅 $each 修饰符。

要添加的值是一个文档

如果值是一个文档，MongoDB 将确定文档是否是重复的，如果数组中现有的文档与要添加的文档完全匹配；即现有文档具有完全相同的字段和值并且字段顺序相同。因此，字段顺序很重要，您不能指定 MongoDB 只比较文档中的一部分字段来确定该文档是否是现有数组元素的重复。

示例

创建 inventory 集合

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

添加到数组

以下操作将元素 "accessories" 添加到 tags 数组中，因为 "accessories" 不存在于数组中

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

值已存在

以下 $addToSet 操作没有效果，因为 "camera" 已经是 tags 数组的一个元素

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

`$each` 修改器

您可以使用 $addToSet 操作符和 $each 修改器。该修改器允许 $addToSet 操作符将多个值添加到数组字段。

集合 inventory 有以下文档

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

以下操作使用 $addToSet 操作符和 $each 修饰符，将多个元素添加到 tags 数组中

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

此操作仅将 "camera" 和 "accessories" 添加到 tags 数组中。 "electronics" 已在数组中

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

提示

另请参阅

$[<标识符>]

下一步

$pop

定义

兼容性

语法

行为