批量写入操作

本页内容

概述

示例数据
定义写入操作
插入操作
更新操作
替换操作
删除操作
运行写入操作
自定义批量写入操作
返回值
处理异常
更多信息

概述

本指南展示了如何使用.NET/C#驱动程序从您的MongoClient实例执行批量写入操作。批量写入操作是对一个或多个MongoDB集合执行多个写入操作的单个数据库调用。与执行多个单独的写入操作相比，这更有效，因为它减少了应用程序和数据库之间的往返次数。

示例数据

本指南中的示例使用来自Atlas示例数据集的sample_restaurants.restaurants集合。要了解如何创建免费的MongoDB Atlas集群并加载数据集，请参阅快速入门教程。

定义写入操作

对于您想要执行的每个写入操作，创建以下之一BulkWriteModel类的实例

BulkWriteInsertOneModel<TDocument>
BulkWriteUpdateOneModel<TDocument>
BulkWriteUpdateManyModel<TDocument>
BulkWriteReplaceOneModel<TDocument>
BulkWriteDeleteOneModel<TDocument>
BulkWriteDeleteManyModel<TDocument>

以下部分展示了如何创建和使用上述类的实例，以在批量写入中执行相应的写入操作。

提示

使用POCO进行批量写入操作

本指南中的示例使用BsonDocument类型作为所有泛型类中TDocument的类型。您还可以使用普通的CLR对象（POCO）来处理这些类。为此，您必须定义一个代表您的集合中文档的类。该类必须具有与您的文档中的字段匹配的属性。有关更多信息，请参阅POCOs。

插入操作

要执行插入操作，创建一个 BulkWriteInsertOneModel<TDocument> 类的实例。该 BulkWriteInsertOneModel<TDocument> 构造函数接受以下参数

参数	描述
`collectionNamespace`	将BSON文档插入到数据库和集合中。数据类型: `string` 或 CollectionNamespace
`document`	要插入到集合中的文档。数据类型: `TDocument`

以下示例创建了一个 BulkWriteInsertOneModel<TDocument> 类的实例。该实例指示驱动程序将包含字段 "name" 值为 "Mongo's Deli" 的文档插入到 sample_restaurants.restaurants 集合中。

var insertOneModel = new BulkWriteInsertOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    new BsonDocument{
        { "name", "Mongo's Deli" },
        { "cuisine", "Sandwiches" },
        { "borough", "Manhattan" },
        { "restaurant_id", "1234" }
    }
);

提示

插入多个文档

要插入多个文档，为要插入的每个文档创建一个 BulkWriteInsertOneModel<TDocument> 类的实例。

更新操作

要更新单个文档，创建一个 BulkWriteUpdateOneModel<TDocument> 类的实例。 BulkWriteUpdateOneModel<TDocument> 构造函数接受以下参数

参数	描述
`collectionNamespace`	将BSON文档插入到数据库和集合中。数据类型： `string` 或 CollectionNamespace
`filter`	查询过滤器指定了用于匹配集合中文档的准则。 `UpdateOne` 操作更新符合查询过滤器的第一个文档。数据类型： FilterDefinition<TDocument>
`update`	您想要执行的操作更新。有关更新操作的更多信息，请参阅MongoDB服务器手册中的字段更新运算符。数据类型： UpdateDefinition<TDocument>
`collation`	可选。排序结果时使用的语言排序规则。有关更多信息，请参阅{+mdb+server+} 手册。数据类型： Collation 默认值： `null`
`hint`	可选。用于扫描文档的索引。有关更多信息，请参阅MongoDB服务器手册。数据类型： BsonValue 默认值： `null`
`isUpsert`	可选。指定更新操作在查询过滤器不匹配任何文档时是否执行upsert操作。有关更多信息，请参阅MongoDB服务器手册。数据类型： `布尔型` 默认值： `false`
`arrayFilters`	指定要修改的数组元素以对数组字段执行更新操作。有关更多信息，请参阅MongoDB服务器手册。数据类型： IEnumerable＜ArrayFilterDefinition＞默认值： `null`

以下代码示例中，BulkWriteUpdateOneModel＜BsonDocument＞对象表示对sample_restaurants.restaurants集合的更新操作。该操作匹配集合中name字段的值为"Mongo's Deli"的第一个文档。然后，将匹配文档中cuisine字段的值更新为"Sandwiches and Salads"。

var updateOneModel = new BulkWriteUpdateOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);

要更新多个文档，创建一个BulkWriteUpdateManyModel＜TDocument＞类的实例。此类的构造函数接受与BulkWriteUpdateOneModel＜TDocument＞构造函数相同的参数。该BulkWriteUpdateManyModel＜TDocument＞操作更新所有匹配您查询过滤器的文档。

以下代码示例中，BulkWriteUpdateManyModel＜BsonDocument＞对象表示对sample_restaurants.restaurants集合的更新操作。该操作匹配集合中所有name字段的值为"Mongo's Deli"的文档。然后，将匹配文档中cuisine字段的值更新为"Sandwiches and Salads"。

var updateManyModel = new BulkWriteUpdateManyModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
    Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
);

替换操作

要替换文档中的字段，请创建一个BulkWriteReplaceOneModel<TDocument>类的实例。BulkWriteReplaceOneModel<TDocument>构造函数接受以下参数：

参数	描述
`collectionNamespace`	将BSON文档插入到数据库和集合中。数据类型： `string` 或 CollectionNamespace
`filter`	查询过滤器指定了用于匹配集合中文档的准则。 `UpdateOne` 操作更新符合查询过滤器的第一个文档。数据类型： FilterDefinition<TDocument>
`replacement`	要替换的文档，其中指定了要在目标文档中插入的字段和值。数据类型: `TDocument`
`collation`	可选。在排序结果时使用的语言排序规则。有关更多信息，请参阅MongoDB服务器手册。数据类型： Collation 默认值： `null`
`hint`	可选。用于扫描文档的索引。有关更多信息，请参阅MongoDB服务器手册。数据类型： BsonValue 默认值： `null`
`isUpsert`	可选。指定更新操作在查询过滤器不匹配任何文档时是否执行upsert操作。有关更多信息，请参阅MongoDB服务器手册。数据类型： `布尔型` 默认值： `false`

在以下示例中，BulkWriteReplaceOneModel<BsonDocument>对象表示对sample_restaurants.restaurants集合的替换操作。该操作匹配集合中restaurant_id字段值为"1234"的文档。然后从这个文档中删除除_id之外的所有字段，并在name、cuisine、borough和restaurant_id字段中设置新值。

var replaceOneModel = new BulkWriteReplaceOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234"),
    new BsonDocument{
        { "name", "Mongo's Pizza" },
        { "cuisine", "Pizza" },
        { "borough", "Brooklyn" },
        { "restaurant_id", "5678" }
    }
);

提示

替换多个文档

要替换多个文档，请为每个要替换的文档创建一个BulkWriteReplaceOneModel<TDocument>类的实例。

删除操作

要删除文档，请创建一个BulkWriteDeleteOneModel<TDocument>类的实例。BulkWriteDeleteOneModel<TDocument>构造函数接受以下参数：

参数	描述
`collectionNamespace`	将BSON文档插入到数据库和集合中。数据类型： `string` 或 CollectionNamespace
`filter`	查询过滤器，用于指定匹配您集合中文档的准则。`DeleteOne`操作仅删除与查询过滤器匹配的第一个文档。数据类型： FilterDefinition<TDocument>
`collation`	可选。在排序结果时使用的语言排序规则。有关更多信息，请参阅MongoDB服务器手册。数据类型： Collation 默认值： `null`
`hint`	可选。用于扫描文档的索引。有关更多信息，请参阅MongoDB服务器手册。数据类型： BsonValue 默认值： `null`

在以下代码示例中，BulkWriteDeleteOneModel<BsonDocument>对象表示对sample_restaurants.restaurants集合的删除操作。该操作匹配并删除第一个restaurant_id字段值为"5678"的文档。

var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);

要删除多个文档，请创建一个BulkWriteDeleteManyModel<TDocument>类的实例，并传递一个查询过滤器来指定要删除的文档。DeleteMany操作删除与您的查询过滤器匹配的所有文档。

在以下代码示例中，BulkWriteDeleteManyModel<BsonDocument>对象表示对sample_restaurants.restaurants集合的删除操作。该操作匹配并删除所有name字段值为"Mongo's Deli"的文档。

var deleteManyModel = new BulkWriteDeleteManyModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli")
);

运行写入操作

定义每个要执行的操作的 BulkWriteModel 实例之后，创建一个实现 IReadOnlyList 接口类的实例。将您的 BulkWriteModel 对象添加到这个 IReadOnlyList 中，然后将 IReadOnlyList 传递给 BulkWrite() 或 BulkWriteAsync() 方法。默认情况下，这些方法按照在集合中定义的顺序执行操作。

提示

IReadOnlyList

Array 和 List 是两个实现 IReadOnlyList 接口常见的类。

选择以下选项卡以查看如何使用异步的 BulkWriteAsync() 方法以及同步的 BulkWrite() 方法来执行批量写入操作。

var client = new MongoClient("mongodb://localhost:27017");
var collection = "sample_restaurants.restaurants";
var bulkWriteModels = new[]
{
    new BulkWriteInsertOneModel<BsonDocument>(
        collection,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new BulkWriteInsertOneModel<BsonDocument>(
        collection,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Brooklyn" },
            { "restaurant_id", "5678" }
        }
    ),
    new BulkWriteUpdateManyModel<BsonDocument>(
        collection,
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new BulkWriteDeleteOneModel<BsonDocument>(
        collection,
        Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234")
    )
};
var results = await client.BulkWriteAsync(bulkWriteModels);
Console.WriteLine("Bulk write results: " + results);

var client = new MongoClient("mongodb://localhost:27017");
var collection = "sample_restaurants.restaurants";
var bulkWriteModels = new[]
{
    new BulkWriteInsertOneModel<BsonDocument>(
        collection,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Manhattan" },
            { "restaurant_id", "1234" }
        }
    ),
    new BulkWriteInsertOneModel<BsonDocument>(
        collection,
        new BsonDocument{
            { "name", "Mongo's Deli" },
            { "cuisine", "Sandwiches" },
            { "borough", "Brooklyn" },
            { "restaurant_id", "5678" }
        }
    ),
    new BulkWriteUpdateManyModel<BsonDocument>(
        collection,
        Builders<BsonDocument>.Filter.Eq("name", "Mongo's Deli"),
        Builders<BsonDocument>.Update.Set("cuisine", "Sandwiches and Salads")
    ),
    new BulkWriteDeleteOneModel<BsonDocument>(
        collection,
        Builders<BsonDocument>.Filter.Eq("restaurant_id", "1234")
    )
};
var results = client.BulkWrite(bulkWriteModels);
Console.WriteLine("Bulk write results: " + results);

前面的代码示例产生以下输出

BulkWriteResult({'writeErrors': [], 'writeConcernErrors': [], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 2, 'nModified': 2, 'nRemoved': 1, 'upserted': []}, acknowledged=True)

自定义批量写入操作

调用 BulkWrite() 或 BulkWriteAsync() 方法时，您可以传递一个 ClientBulkWriteOptions 类的实例。该 ClientBulkWriteOptions 类包含以下属性，这些属性代表您可以用于配置批量写入操作的选项

属性	描述
`BypassDocumentValidation`	指定操作是否绕过文档级别的验证。有关更多信息，请参阅 MongoDB 服务器手册中的模式验证。默认为 `false`。
`注释`	将附加到操作的一个注释，形式为 `BsonValue`。有关更多信息，请参阅 MongoDB 服务器手册中的删除命令字段指南。
`IsOrdered`	如果 `true`，驱动程序将按照提供的顺序执行写操作。如果发生错误，则不会尝试剩余的操作。如果 `false`，驱动程序将以任意顺序执行操作并尝试执行所有操作。如果无序批量写操作中的任何写操作失败，驱动程序将在尝试所有操作后报告错误。默认为 `True`。
`Let`	参数名称和值的映射，形式为 `BsonDocument`。值必须是常量或封闭表达式，不能引用文档字段。有关更多信息，请参阅 MongoDB 服务器手册中的 let 语句。
`VerboseResult`	指定操作返回的 `ClientBulkWriteResult` 对象是否包含每个成功写操作的确切结果。默认为 `false`。
`WriteConcern`	作为 `WriteConcern` 枚举值的写操作使用的写关注。默认为操作正在运行的集合的写关注。

以下代码示例使用 ClientBulkWriteOptions 对象自定义删除操作

var client = new MongoClient("mongodb://localhost:27017");
var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);
var clientBulkWriteOptions = new ClientBulkWriteOptions
{
    IsOrdered = false,
    WriteConcern = WriteConcern.Unacknowledged,
    VerboseResult = true
};
var results = await client.BulkWriteAsync(deleteOneModel, clientBulkWriteOptions);

var client = new MongoClient("mongodb://localhost:27017");
var deleteOneModel = new BulkWriteDeleteOneModel<BsonDocument>(
    "sample_restaurants.restaurants",
    Builders<BsonDocument>.Filter.Eq("restaurant_id", "5678")
);
var clientBulkWriteOptions = new ClientBulkWriteOptions
{
    IsOrdered = false,
    WriteConcern = WriteConcern.Unacknowledged,
    VerboseResult = true
};
var results = client.BulkWrite(deleteOneModel, clientBulkWriteOptions);

返回值

BulkWrite() 和 BulkWriteAsync() 方法返回一个包含以下属性的 ClientBulkWriteResult 对象

属性	描述
`Acknowledged`	指示服务器是否确认了批量写操作。如果此属性的值为 `false`，并且您尝试访问 `ClientBulkWriteResult` 对象的任何其他属性，驱动程序将抛出异常。
`DeleteResults`	包含每个成功删除操作结果的 `IReadOnlyDictionary<int, BulkWriteDeleteResult>` 对象（如果有的话）。
`DeletedCount`	已删除的文档数量（如果有的话）。
`InsertResults`	包含每个成功插入操作结果的 `IReadOnlyDictionary<int, BulkWriteInsertOneResult>` 对象（如果有的话）。
`InsertedCount`	插入的文档数量（如果有的话）。
`MatchedCount`	适用的更新中匹配的文档数量。
`ModifiedCount`	修改的文档数量（如果有的话）。
`UpsertResults`	包含每个成功更新操作结果的 `IReadOnlyDictionary<int, BulkWriteUpdateResult>` 对象（如果有的话）。
`UpsertedCount`	upserted的文档数量（如果有的话）。

处理异常

如果批量写入操作中的任何操作失败，.NET/C# 驱动程序将抛出 ClientBulkWriteException 异常，并且不会执行任何进一步的操作。

ClientBulkWriteException 对象包含以下属性

属性	描述
`connectionId`	连接标识符。数据类型： ConnectionId
`message`	错误信息。数据类型： string
`writeErrors`	在批量写入操作期间发生的错误字典。数据类型： IReadOnlyDictionary<int, WriteError>
`partialResult`	在抛出异常之前执行的成功操作的结果。数据类型: ClientBulkWriteResult
`writeConcernErrors`	在执行批量写操作期间发生的写关注错误。数据类型: IReadOnlyList<MongoWriteConcernException>
`innerException`	内部异常。数据类型: Exception

附加信息

要了解如何执行单个写入操作，请参阅以下指南

要了解更多关于本指南中讨论的任何方法或类型的信息，请参阅以下API文档

删除

读取