$addToSet

在此页面上

定义

兼容性
语法
行为
示例

定义

$addToSet: $addToSet 操作符将值添加到数组中，除非该值已经存在，在这种情况下，$addToSet 对该数组不执行任何操作。

兼容性

可以使用 $addToSet 查找托管在以下环境中的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

$addToSet 操作符具有如下形式：

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

要在嵌入式文档或数组中指定 <field>，请使用点符号。

行为

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

$addToSet 仅可确保向集合添加的项目不会重复，并且不会影响现有的重复元素。$addToSet 不保证修改后集合中元素的特定排序。

从 MongoDB 5.0 开始，使用带空操作数表达式 ({ }) 的更新操作符（如 $addToSet）时，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` 修饰符

您可以使用带有 $each 修饰符的 $addToSet 操作符。$each 修饰符允许 $addToSet 操作符在数组字段中添加多个值。

集合 inventory 包含以下文档：

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

然后，以下操作使用带有 $each 修饰符的 $addToSet 操作符向 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" ]
}

提示

另请参阅：

后退

$[<identifier>]

来年

$pop

定义

兼容性

语法

行为