更新构建器
在此页面上
Overview
在本指南中，您可以学习；了解如何使用MongoDB Kotlin驱动程序中的 构建者 来指定 更新 。
Updates 构建器为以下类型的更新提供辅助方法：
一些需要更新的方法包括：
updateOne()updateMany()bulkWrite()
Updates 类为所有 MongoDB 更新运算符提供静态工厂方法。每个方法都返回一个 BSON 类型的实例，您可以将其传递给任何需要更新参数的方法。
提示
为了简洁起见，您可以选择将 Updates 方法导入 class:
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 ( 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" } }
Set On Insert
使用 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字段的值（即5 ）乘以2 ：
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
使用 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
使用 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 } }
Bit
使用 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" } }
Array Updates
Add to Set
如果更新操作中尚不存在某值，则使用 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" } }
Pull All
使用 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
使用 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() 方法在更新操作中将值附加到数组。
以下示例将name值为"Q"的Vendor实例添加到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" } }