更新构建器

概述

在本指南中，您可以学习如何使用构建器在MongoDB Kotlin驱动程序中指定更新。

以下是一些提供辅助方法的更新构建器：Updates构建器提供了以下类型更新的辅助方法

字段更新
数组更新
组合多个更新运算符

一些期望更新参数的方法包括

updateOne()
updateMany()
bulkWrite()

Updates类为所有MongoDB更新操作符提供了静态工厂方法。每个方法都返回一个BSON类型的实例，您可以将它传递给任何期望更新参数的方法。

提示

为了简洁起见，您可以选择导入Updates类的

import com.mongodb.client.model.Updates.*

本指南中的示例使用以下文档

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

除非另有说明，否则本例基于以下数据类建模

data class PaintOrder (
    @BsonId val id: Int,
    val color: String,
    val qty: Int?,
    val vendor: List<Vendor>?,
    val lastModified: LocalDateTime?
)
data class Vendor (
    val name: String,
)

字段更新

设置

使用 set() 方法来在更新操作中分配字段的值。

以下示例将 qty 字段的值设置为 11。

val filter = Filters.eq("_id", 1)
val update = Updates.set(PaintOrder::qty.name, 11)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 11,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

未设置

使用 unset() 方法在更新操作中删除字段的值。

以下示例删除了 qty 字段

val filter = Filters.eq("_id", 1)
val update = Updates.unset(PaintOrder::qty.name)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

设置插入时

使用 setOnInsert() 方法在插入文档时为更新操作中的字段分配值。

以下示例在操作导致插入文档的情况下，将 color 字段的值设置为 "pink"。

val filter = Filters.eq("_id", 1)
val update = Updates.setOnInsert(PaintOrder::color.name, "pink")
collection.updateOne(filter, update, UpdateOptions().upsert(true))

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "pink"
}

注意

如果文档没有插入，则不会发生任何更改。

增加

使用 inc() 方法在更新操作中增加数值字段的值。

以下示例将 qty 字段的值（原值为 5）增加 3。

val filter = Filters.eq("_id", 1)
val update = Updates.inc(PaintOrder::qty.name, 3)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

乘以

使用mul()方法来在更新操作中乘以一个数值字段的值。

以下示例将qty字段的值乘以2，该字段的原始值为5。

val filter = Filters.eq("_id", 1)
val update = Updates.mul(PaintOrder::qty.name, 2)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 10,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

重命名

使用rename()方法来重命名更新操作中字段的值。

以下示例将qty字段重命名为quantity。

val filter = Filters.eq("_id", 1)
val update = Updates.rename(PaintOrder::qty.name, "quantity")
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" },
   "quantity": 5,
}

Min

使用min()方法将字段的值设置为给定值，如果给定值小于字段当前值。

以下示例将qty字段更新为2，因为2小于当前qty字段的值（5）。

val filter = Filters.eq("_id", 1)
val update = Updates.min(PaintOrder::qty.name, 2)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 2,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

最大值

使用max() 方法来更新更新操作中指定的两个值中较大的值所对应的字段值。

以下示例将 qty 字段更新为 8，因为 8 大于当前 qty 字段（5）的值。

val filter = Filters.eq("_id", 1)
val update = Updates.max(PaintOrder::qty.name, 8)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 8,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

当前日期

使用 currentDate() 方法将更新操作中字段的值设置为当前日期，作为 BSON 日期。

以下示例将 lastModified 字段的值设置为当前日期作为 BSON 日期

val filter = Filters.eq("_id", 1)
val update = Updates.currentDate(PaintOrder::lastModified.name)
collection.updateOne(filter, update)

自2023年6月16日我们编写此页面以来，前面的示例已将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "$date": "2023-06-16T17:13:06.373Z"
}

当前时间戳

使用 currentTimestamp() 方法将更新操作中字段的值设置为当前日期作为时间戳。

以下示例将 lastModified 字段的值设置为当前日期作为 BSON 时间戳

// Create a new instance of the collection with the flexible `Document` type
// to allow for the changing of the `lastModified` field to a `BsonTimestamp`
// from a `LocalDateTime`.
val collection = database.getCollection<Document>("paint_orders")
val filter = Filters.eq("_id", 1)
val update = Updates.currentTimestamp(PaintOrder::lastModified.name)
collection.updateOne(filter, update)

自2023年6月16日我们编写此页面以来，前面的示例已将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "$timestamp": { "t": 1686935654, "i": 3 }
}

位

使用 bitwiseOr()、bitwiseAnd() 和 bitwiseXor() 方法来执行更新操作中对字段整数值的位运算更新。

以下示例在数字 10 和字段 qty 的整数值（5）之间执行位运算 OR。

val filter = Filters.eq("_id", 1)
val update = Updates.bitwiseOr(PaintOrder::qty.name, 10)
collection.updateOne(filter, update)

位运算的结果为 15。

0101 // bit representation of 5
1010 // bit representation of 10
----
1111 // bit representation of 15

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 15,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

数组更新

添加到集合

使用 addToSet() 方法在更新操作中向数组追加一个值，如果该值尚未存在。

以下示例将一个具有 name 值为 "C" 的 Vendor 实例添加到 vendor 数组。

val filter = Filters.eq("_id", 1)
val update = Updates.addToSet(PaintOrder::vendor.name, Vendor("C"))
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "C" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

Pop

使用 popFirst() 方法从数组中删除第一个元素，以及使用 popLast() 方法从更新操作中的数组中删除最后一个元素。

以下示例删除了 vendor 数组的第一个条目

val filter = Filters.eq("_id", 1)
val update = Updates.popFirst(PaintOrder::vendor.name)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "D" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

全部拉取

使用 pullAll() 方法从更新操作中的现有数组中删除指定值的所有实例。

以下示例从 vendor 数组中删除具有 name 值为 "A" 和 "M" 的 Vendor 实例

val filter = Filters.eq("_id", 1)
val update = Updates.pullAll(PaintOrder::vendor.name, listOf(Vendor("A"), Vendor("M")))
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "D" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

拉取

使用 pull() 方法从更新操作中的现有数组中删除指定值的所有实例。

以下示例从 vendor 数组中删除具有 name 值为 "D" 的 Vendor 实例

val filter = Filters.eq("_id", 1)
val update = Updates.pull(PaintOrder::vendor.name, Vendor("D"))
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "M" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

使用
方法在更新操作中向数组中追加值。

使用push()方法向更新操作中的数组追加一个值。

以下示例向vendor数组添加一个名为"Q"的Vendor实例。

val filter = Filters.eq("_id", 1)
val update = Updates.push(PaintOrder::vendor.name, Vendor("Q"))
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "red",
   "qty": 5,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "Q" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

组合多个更新操作符

应用程序可以通过组合前几节中描述的两个或多个更新操作符来更新单个文档的多个字段。

以下示例将 qty 字段的值增加 6，将 color 字段的值设置为 "purple"，并将一个具有 name 值为 "R" 的 Vendor 实例添加到 vendor 字段

val filter = Filters.eq("_id", 1)
val update = Updates.combine(
    Updates.set(PaintOrder::color.name, "purple"),
    Updates.inc(PaintOrder::qty.name, 6),
    Updates.push(PaintOrder::vendor.name, Vendor("R"))
)
collection.updateOne(filter, update)

前面的示例将原始文档更新为以下状态

{
   "_id": 1,
   "color": "purple",
   "qty": 11,
   "vendor": [
      { "name": "A" },
      { "name": "D" },
      { "name": "M" },
      { "name": "R" }
   ],
   "lastModified": { "$date": "2000-01-01T07:00:00.000Z" }
}

排序

下一步

聚合

概述

提示

字段更新

设置

未设置

设置插入时

注意

增加

乘以

重命名

Min

最大值

当前日期

当前时间戳

位

数组更新

添加到集合

Pop

全部拉取

拉取

使用方法在更新操作中向数组中追加值。

组合多个更新操作符

使用
方法在更新操作中向数组中追加值。