Docs 菜单
Docs 主页
/ / /
C#/.NET
/ / /

插入文档

在此页面上

  • Overview
  • 样本数据
  • _id 字段
  • 插入一个文档
  • 插入多个文档
  • 修改插入行为
  • 例子
  • 指定有序行为
  • 更多信息
  • API 文档

在本指南中,您可以了解如何使用 MongoDB .NET/C# 驱动程序通过执行插入操作将文档添加到 MongoDB 集合。

注意

16 MB 大小限制

MongoDB将单个BSON文档限制为16 MB。如果您的文档大于16 MB,请改用 GridFS API 。

插入操作会在 MongoDB 集合中插入一个或多个文档。.NET/C# Driver 提供了以下方法来执行插入操作,每种方法都有异步和同步版本:

  • InsertOneAsync() or InsertOne()

  • InsertManyAsync() or InsertMany()

提示

互动实验室

本页包括一个简短的交互式实验室,演示了如何使用 InsertOneAsync() 方法插入数据。无需安装 MongoDB 或代码编辑器,即可直接在浏览器窗口中完成此实验。

若要启动实验室,请单击页面顶部的“Open Interactive Tutorial”按钮。要将实验室扩展为全屏格式,请单击实验室窗格右上角的全屏按钮 ()。

本指南中的示例使用 sample_restaurants 数据库中的 restaurants 集合。此集合中的文档使用以下 RestaurantAddressGradeEntry 类作为模型:

public class Restaurant
{
public ObjectId Id { get; set; }
public string Name { get; set; }
[BsonElement("restaurant_id")]
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; }
[BsonElement("coord")]
public double[] Coordinates { get; set; }
public string Street { get; set; }
[BsonElement("zipcode")]
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 cluster并加载此示例数据。

在 MongoDB 集合中,每个文档必须包含具有唯一字段值的 _id 字段。

MongoDB 允许您通过两种方式管理该字段:

  • 您可以自行为每个文档设置此字段,确保每个 _id 字段的值都是唯一的。

  • 您可以让驱动程序为每个文档 _id 自动生成唯一的 ObjectId 值。如果您没有为文档手动设置 _id 字段值,则驱动程序将用 ObjectId 填充该字段。

除非您可以保证唯一性,否则 MongoDB 建议让驱动程序自动生成 _id 值。

注意

重复的 _id 值违反了唯一索引约束条件,会导致驱动程序从 InsertOne() 返回 MongoWriteException,或从 InsertMany() 返回 MongoBulkWriteException

如要了解有关 _id 字段的更多信息,请参阅有关唯一索引的 Server 手册条目。

要了解有关文档结构和规则的更多信息,请参阅服务器手册中有关文档的条目。

如下代码将演示如何使用异步 InsertOneAsync() 方法或同步 InsertOne() 方法插入一个文档。

await _restaurantsCollection.InsertOneAsync(document);
_restaurantsCollection.InsertOne(document);

如下代码将演示如何使用异步 InsertManyAsync() 方法或同步 InsertMany() 方法插入多个文档。

await _restaurantsCollection.InsertManyAsync(docs);
_restaurantsCollection.InsertMany(docs);

提示

附加信息下方,使用这些方法查找可运行的示例。

InsertOne() 方法将您要插入的文档作为参数。InsertMany()方法采用 IEnumerable 文档集合(例如列表或数组)作为参数。

InsertOne() 方法可以选择性地采用 InsertOneOptions 类型作为附加参数,此参数表示可用来配置插入操作的选项。如果您不指定任何 InsertOneOptions 属性,驱动程序将不会自定义插入操作。

InsertOneOptions 类型允许您使用以下属性配置选项:

属性
说明

BypassDocumentValidation

Gets or sets a value indicating whether to bypass document validation. If true, allows the write to opt-out of document level validation.

Comment

Gets or sets the comment for the operation. See the insert command fields for more information.

InsertMany() 方法可以选择采用 InsertManyOptions 类型作为附加参数,该参数具有前面的 BypassDocumentValidationComment 属性,以及附加的 IsOrdered 属性:

属性
说明

IsOrdered

Gets or sets a value indicating whether the requests are fulfilled in order. If true, the driver sends documents to the server in the order provided. If an error occurs, the driver and server abort all remaining insert operations. To learn more, see Ordered Behavior.
Default: true

以下代码使用InsertMany() 方法将五个新的文档插入到collection中,并将Restaurant BypassDocumentValidation设置为true

// Generates 5 new restaurants by using a helper method
var restaurants = GenerateDocuments();
// Creates an option object to bypass documentation validation on the documents
var options = new InsertManyOptions() { BypassDocumentValidation = true };
// Inserts the new documents into the restaurants collection with the specified options
_restaurantsCollection.InsertMany(restaurants, options);

InsertMany() 方法没有返回值。您可以通过对集合执行 Find() 操作来验证文档是否已成功插入。有关如何查找文档的示例,请参阅查找文档

假设要插入以下文档:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 1, "name" : "Restaurant C" }
{ "_id" : 3, "name" : "Restaurant D" }

如果您尝试使用默认 InsertManyOptions 插入这些文档,由于 _id 值重复,驱动程序会在插入第三个文档时抛出 MongoBulkWriteException,但出错文档之前的文档仍会插入到您的集合中。

当查看集合内部时,您应当能够看到以下文档:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }

如果您在插入操作中将 IsOrdered 设置为 false,则即使某些文档产生错误,驱动程序也会继续插入文档。通过此修改后的插入行为,驱动程序抛出异常,但将插入所有不会产生错误的文档。

当查看集合内部时,您应当能够看到以下文档:

{ "_id" : 1, "name" : "Restaurant A" }
{ "_id" : 2, "name" : "Restaurant B" }
{ "_id" : 3, "name" : "Restaurant D" }

有关插入操作的可运行示例,请参阅以下使用示例:

要进一步了解本指南所讨论的任何方法或类型,请参阅以下 API 文档:

后退

写入