修改文档
Overview
在本指南中,您可以了解如何使用 MongoDB .NET/C# 驱动程序,以通过执行以下操作来修改 MongoDB 集合中的文档:
.NET/C# 驱动程序提供了以下方法修改文档,每种方法都有异步和同步版本:
UpdateOneAsync()
orUpdateOne()
UpdateManyAsync()
orUpdateMany()
ReplaceOneAsync()
orReplaceOne()
提示
互动实验室
本页包括一个简短的交互式实验室,演示了如何使用 UpdateManyAsync()
方法修改数据。无需安装 MongoDB 或代码编辑器,即可直接在浏览器窗口中完成此实验。
若要启动实验室,请单击页面顶部的“Open Interactive Tutorial”按钮。要将实验室扩展为全屏格式,请单击实验室窗格右上角的全屏按钮 (⛶)。
样本数据
本指南中的示例使用 sample_restaurants
数据库中的 restaurants
集合。此集合中的文档使用以下 Restaurant
、Address
和 GradeEntry
类作为模型:
public class Restaurant { public ObjectId Id { get; set; } public string Name { get; set; } [ ] public string RestaurantId { get; set; } public string Cuisine { get; set; } public Address Address { get; set; } public string Borough { get; set; } public List<GradeEntry> Grades { get; set; } }
public class Address { public string Building { get; set; } [ ] public double[] Coordinates { get; set; } public string Street { get; set; } [ ] public string ZipCode { get; set; } }
public class GradeEntry { public DateTime Date { get; set; } public string Grade { get; set; } public float? Score { get; set; } }
注意
restaurants
集合中的文档使用蛇形命名规则。本指南中的示例使用 ConventionPack
将集合中的字段反序列化为 Pascal 语句,并将它们映射到 Restaurant
类中的属性。
如需了解有关自定义序列化的更多信息,请参阅自定义序列化。
此数据集来自 Atlas 提供的示例数据集。请参阅快速入门,以了解如何创建一个免费的 MongoDB 集群并加载这些示例数据。
更新操作
您可以通过以下方法在 MongoDB 中执行更新操作:
UpdateOne()
,更新匹配搜索条件的第一个文档UpdateMany()
,更新与搜索条件匹配的所有文档
所需参数
每种更新方法都需要以下参数:
查询筛选器文档,用于确定要更新的记录。 有关查询筛选器的更多信息,请参阅MongoDB 服务器手册。
更新文档,其中指定更新操作符(要执行的更新类型)以及应更改的字段和值。 有关更新操作符及其用法的完整列表,请参阅字段更新操作符手册页面。
.NET/C# 驱动程序提供了一个 Builders
类,可简化查询筛选器和更新文档的创建。以下代码示例使用 Builders
创建两个文档以用作更新操作中的参数:
查询过滤器,用于搜索
cuisine
字段值为“Pizza”的餐厅更新文档,用于将这些餐厅的
cuisine
字段的值设置为 "Pasta and breadsticks"
const string oldValue = "Pizza"; const string newValue = "Pasta and breadsticks"; // Creates a filter for all documents with a "cuisine" value of "Pizza" var filter = Builders<Restaurant>.Filter .Eq(restaurant => restaurant.Cuisine, oldValue); // Creates instructions to update the "cuisine" field of documents that // match the filter var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Cuisine, newValue); // Updates all documents that have a "cuisine" value of "Pizza" return _restaurantsCollection.UpdateMany(filter, update);
提示
更新操作中的聚合管道
如果您使用的是 MongoDB 4.2或更高版本,则可以在更新操作中使用由聚合阶段子集组成的聚合管道。 有关 MongoDB 在更新操作中使用的聚合管道中支持的聚合阶段的更多信息,请参阅有关使用聚合管道构建更新的教程。
更新一个文档
以下代码将演示如何使用异步 UpdateOneAsync()
方法或同步 UpdateOne()
方法更新一个文档。
var result = await _restaurantsCollection.UpdateOneAsync(filter, update);
var result = _restaurantsCollection.UpdateOne(filter, update);
更新多个文档
以下代码将演示如何使用异步 UpdateManyAsync()
方法或同步 UpdateMany()
方法更新所有匹配文档。
var result = await _restaurantsCollection.UpdateManyAsync(filter, update);
var result = _restaurantsCollection.UpdateMany(filter, update);
提示
在附加信息下方查找使用这些方法的可运行示例。
自定义更新操作
这两种方法都可以选择接受 UpdateOptions
对象作为附加参数,该参数表示可用于配置更新操作的选项。如果您不指定任何 UpdateOptions
属性,则驱动程序不会自定义更新操作。
UpdateOptions
类型允许您使用以下属性配置选项:
属性 | 说明 |
---|---|
| Specifies which array elements to modify for an update operation on an array field.
See the MongoDB server manual
for more information. |
| Specifies whether the update operation bypasses document validation. This lets you
update documents that don't meet the schema validation requirements, if any
exist. See the MongoDB server manual
for more information on schema validation. |
| Specifies the kind of language collation to use when sorting
results. See the MongoDB server manual
for more information on collation. |
| Gets or sets the user-provided comment for the operation.
See the MongoDB server manual
for more information. |
| Gets or sets the index to use to scan for documents.
See the MongoDB server manual
for more information. |
| Specifies whether the update operation performs an upsert operation if no
documents match the query filter.
See the MongoDB server manual
for more information. |
| Gets or sets the let document.
See the MongoDB server manual
for more information. |
返回值
UpdateOne()
和 UpdateMany()
方法会各自返回一个 UpdateResult
对象。UpdateResult
类型包含以下属性:
属性 | 说明 |
---|---|
| Indicates whether the update operation was acknowledged by MongoDB. |
| Indicates whether you can read the count of updated records on the
UpdateResult . |
| The number of documents that matched the query filter, regardless of
how many were updated. |
| The number of documents updated by the update operation. If an updated
document is identical to the original, it won't be included in this count. |
| The ID of the document that was upserted in the database, if the driver
performed an upsert. |
例子
以下代码使用 UpdateMany()
方法查找 borough
字段值为“曼哈顿”的所有文档,然后将这些文档中的 borough
值更新为“曼哈顿(北部)”。由于 IsUpsert
选项设置为 true
,因此如果查询筛选器与任何现有文档都不匹配,驱动程序将插入新文档。
var filter = Builders<Restaurant>.Filter .Eq(restaurant => restaurant.Borough, "Manhattan"); var update = Builders<Restaurant>.Update .Set(restaurant => restaurant.Borough, "Manhattan (north)"); UpdateOptions opts = new UpdateOptions() { Comment = new BsonString("Borough updated for C# Driver Fundamentals"), IsUpsert = true }; Console.WriteLine("Updating documents..."); var result = _restaurantsCollection.UpdateMany(filter, update, opts); Console.WriteLine($"Updated documents: {result.ModifiedCount}"); Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");
Updating documents... Updated documents: 10259 Result acknowledged? True
注意
如果上述示例使用 UpdateOne()
方法而不是 UpdateMany()
,则驱动程序将更新匹配文档中的第一个。
替换操作
您可以使用 ReplaceOne()
方法在 MongoDB 中执行替换操作。此方法会删除第一个符合搜索条件的文档中的所有字段(_id
字段除外),然后将指定的字段和值插入文档。
所需参数
ReplaceOne()
方法需要使用以下参数:
查询筛选器文档,用于确定要替换的记录。
替换文档,用于指定要插入新文档的字段和值。如果集合中的文档映射到 C# 类,则替换文档可以是此类的实例。
与更新操作一样,您可以使用 .NET/C# 驱动程序中的 Builders
类来创建查询筛选器。以下代码示例使用 Builders
创建查询筛选器,用于搜索 name
字段值为“Pizza Town”的餐厅。该代码还创建一个新的 Restaurant
对象,以替换第一个匹配的文档。
// Creates a filter for all restaurant documents that have a "cuisine" value of "Pizza" var filter = Builders<Restaurant>.Filter .Eq(r => r.Cuisine, "Pizza"); // Finds the ID of the first restaurant document that matches the filter var oldPizzaRestaurant = _restaurantsCollection.Find(filter).First(); var oldId = oldPizzaRestaurant.Id; // Generates a new restaurant document Restaurant newPizzaRestaurant = new() { Id = oldId, Name = "Mongo's Pizza", Cuisine = "Pizza", Address = new() { Street = "Pizza St", ZipCode = "10003" }, Borough = "Manhattan", }; // Replaces the existing restaurant document with the new document return _restaurantsCollection.ReplaceOne(filter, newPizzaRestaurant);
重要
_id
字段的值不可变。如果您的替换文档指定 _id
字段的值,则它必须与现有文档的 _id
值匹配。
以下代码将演示如何使用异步 ReplaceOneAsync()
方法或同步 ReplaceOne()
方法替换一个文档。
var result = await _restaurantsCollection.ReplaceOneAsync(filter, newRestaurant);
var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant);
提示
在附加信息下方查找使用这些方法的可运行示例。
自定义替换操作
ReplaceOne()
方法可以选择性地采用 ReplaceOptions
对象作为附加参数,此参数表示可用来配置替换操作的选项。如果您不指定任何 ReplaceOptions
属性,则驱动程序不会自定义替换操作。
ReplaceOptions
类型允许您使用以下属性配置选项:
属性 | 说明 |
---|---|
| Specifies whether the replace operation bypasses document validation. This lets you
replace documents that don't meet the schema validation requirements, if any
exist. See the MongoDB server manual
for more information on schema validation. |
| Specifies the kind of language collation to use when sorting
results. See the MongoDB server manual
for more information on collation. |
| Gets or sets the user-provided comment for the operation.
See the MongoDB server manual
for more information. |
| Gets or sets the index to use to scan for documents.
See the MongoDB server manual
for more information. |
| Specifies whether the replace operation performs an upsert operation if no
documents match the query filter.
See the MongoDB server manual
for more information. |
| Gets or sets the let document.
See the MongoDB server manual
for more information. |
返回值
ReplaceOne()
方法返回 ReplaceOneResult
对象。ReplaceOneResult
类型包含以下属性:
属性 | 说明 |
---|---|
| Indicates whether the replace operation was acknowledged by MongoDB. |
| Indicates whether you can read the count of replaced records on the
ReplaceOneResult . |
| The number of documents that matched the query filter, regardless of
whether one was replaced. |
| The number of documents replaced by the replace operation. |
| The ID of the document that was upserted in the database, if the driver
performed an upsert. |
例子
以下代码使用 ReplaceOne()
方法查找 name
字段值为“Pizza Town”的第一个文档,然后用名为“Food World”的新的 Restaurant
文档替换该文档。由于 IsUpsert
选项设置为 true
,因此如果查询筛选器与任何现有文档都不匹配,驱动程序将插入新文档。
var filter = Builders<Restaurant>.Filter.Eq(restaurant => restaurant.Name, "Pizza Town"); Restaurant newRestaurant = new() { Name = "Food World", Cuisine = "American", Address = new BsonDocument { {"street", "Food St"}, {"zipcode", "10003"}, }, Borough = "Manhattan", }; ReplaceOptions opts = new ReplaceOptions() { Comment = new BsonString("Restaurant replaced for .NET/C# Driver Fundamentals"), IsUpsert = true }; Console.WriteLine("Replacing document..."); var result = _restaurantsCollection.ReplaceOne(filter, newRestaurant, opts); Console.WriteLine($"Replaced documents: {result.ModifiedCount}"); Console.WriteLine($"Result acknowledged? {result.IsAcknowledged}");
Replacing document... Replaced documents: 1 Result acknowledged? True
更多信息
有关更新和替换操作的可运行示例,请参阅以下用法示例:
要了解创建查询筛选器的更多信息,请参阅指定查询指南。
API 文档
要进一步了解本指南所讨论的任何方法或类型,请参阅以下 API 文档: