插入文档

本页内容

概述

_id 字段
插入一个文档
示例
修改 insert_one 行为
插入多个文档
示例
修改 insert_many 行为
有序行为示例
更多信息
API 文档

概述

在本指南中，您可以学习如何将文档插入到 MongoDB 集合中。

在您可以在 MongoDB 中查找、更新和删除任何文档之前，您需要先插入它们。您可以使用以下方法来插入文档：

insert_one() 用于插入单个文档
insert_many() 用于插入一个或多个文档

本指南包括以下部分：

_id 字段描述了每个文档包含的 _id 字段
插入文档描述了如何使用驱动程序将单个文档插入到集合中
插入多个文档描述了如何使用驱动程序将多个文档插入到集合中
更多信息提供了本指南中提到的类型和方法的相关资源链接和 API 文档

字段 _id

在MongoDB集合中，每个文档都必须包含一个唯一的 _id 字段值。当您将数据插入集合时，驱动程序会自动为每个文档生成一个唯一的值作为 ObjectId 类型。

如果您希望设置自定义值，可以在传递给插入操作文档的 _id 字段中分配这些值。

重要

重复的 _id 值

如果您尝试插入包含重复 _id 值的文档，这些值违反了唯一索引约束，导致写入操作失败。

有关 _id 字段的更多信息，请参阅服务器手册中的唯一索引。

有关文档结构和规则的更多信息，请参阅服务器手册中的文档。

插入文档

使用 insert_one() 方法将单个文档插入集合。

成功插入后，该方法返回一个包含插入文档 _id 的 InsertOneResult 实例。

示例

以下示例使用 insert_one() 方法将文档插入到 books 集合

let my_coll: Collection<Book> = client.database("db").collection("books");
let doc = Book { _id: 8, title: "Atonement".to_string(), author: "Ian McEwan".to_string() };
let insert_one_result = my_coll.insert_one(doc).await?;
println!("Inserted document with _id: {}", insert_one_result.inserted_id);

Inserted document with _id: 8

提示

不存在的数据库和集合

如果在执行写操作时数据库和集合不存在，服务器将自动创建它们。

修改 insert_one 的行为

您可以通过将选项构建器方法链接到 insert_one() 来修改 insert_one() 方法的行为。这些选项构建器方法设置 InsertOneOptions 结构体字段。

注意

设置选项

您可以通过将选项构建器方法直接链接到 insert_one() 方法调用来设置 InsertOneOptions 字段。如果您正在使用较早版本的驱动程序，您必须通过将选项构建器方法链接到 builder() 方法来构建一个 InsertOneOptions 实例。然后，将您的选项实例作为参数传递给 insert_one()。

以下表格描述了 InsertOneOptions 中可用的选项

选项	描述
`bypass_document_validation`	如果为 `true`，允许驱动程序执行违反文档级验证的写操作。有关验证的更多信息，请参阅关于架构验证的指南。类型: `bool` 默认值: `false`
`write_concern`	操作写入关注点。如果您不设置此选项，则操作继承集合设置的写入关注点。有关写入关注点的更多信息，请参阅服务器手册中的写入关注点。类型: `WriteConcern`
`comment`	一个与操作相关联的任意 `Bson` 值，用于通过数据库分析器、`currentOp` 和日志来跟踪操作。此选项仅在使用 MongoDB 服务器版本 4.4 及更高版本连接时可用。类型: `Bson` 默认值: `None`

以下代码展示了如何通过链式调用 bypass_document_validation() 方法到 insert_one() 方法来设置 bypass_document_validation 字段。

let _result = my_coll.insert_one(doc)
    .bypass_document_validation(true)
    .await?;

插入多个文档

使用 insert_many() 方法将多个文档插入到集合中。

在成功插入后，该方法返回一个包含插入文档 _id 值的 InsertManyResult 实例。

示例

以下示例使用 insert_many() 方法将多个文档插入到 books 集合中。

let docs = vec![
    Book {
        _id: 5,
        title: "Cat's Cradle".to_string(),
        author: "Kurt Vonnegut Jr.".to_string()
    },
    Book {
        _id: 6,
        title: "In Memory of Memory".to_string(),
        author: "Maria Stepanova".to_string()
    },
    Book {
        _id: 7,
        title: "Pride and Prejudice".to_string(),
        author: "Jane Austen".to_string()
    }
];
let insert_many_result = my_coll.insert_many(docs).await?;
println!("Inserted documents with _ids:");
for (_key, value) in &insert_many_result.inserted_ids {
    println!("{:?}", value);
}

Inserted documents with _ids:
Int32(5)
Int32(6)
Int32(7)

提示

不存在的数据库和集合

如果在执行写操作时数据库和集合不存在，服务器将自动创建它们。

修改 insert_many 行为

您可以通过将选项构建器方法链接到 insert_many() 来修改 insert_many() 的行为。这些选项构建器方法设置 InsertManyOptions 结构体字段。

以下表格描述了 InsertManyOptions 中可用的选项

选项	描述
`bypass_document_validation`	如果为 `true`，允许驱动程序执行违反文档级验证的写操作。有关验证的更多信息，请参阅关于架构验证的指南。类型: `bool` 默认值: `false`
`ordered`	如果 `true`，当任何插入操作失败时，该操作将不会插入剩余的文档并返回。如果 `false`，即使插入操作失败，操作也会继续进行剩余的写入。有关按顺序插入的更多信息，请参阅本指南的有序行为示例部分。类型: `bool` 默认值：`true`
`write_concern`	操作写入关注点。如果您不设置此选项，则操作继承集合设置的写入关注点。有关写入关注点的更多信息，请参阅服务器手册中的写入关注点。类型: `WriteConcern`
`comment`	一个与操作相关联的任意 `Bson` 值，用于通过数据库分析器、`currentOp` 和日志来跟踪操作。此选项仅在使用 MongoDB 服务器版本 4.4 及更高版本连接时可用。类型: `Bson` 默认值: `None`

以下代码演示了如何通过将comment()方法链接到insert_many()方法来设置comment字段。

let _result = my_coll.insert_many(docs)
    .comment(Some("hello world".into()))
    .await?;

有序行为示例

假设您想将以下文档插入到books集合中

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 1, "title": "Blueberries for Sal" }
{ "_id": 3, "title": "Goodnight Moon" }

当您尝试插入这些文档时，结果取决于传递给ordered()选项构建器方法的值

如果您传递值为true（默认值），则在尝试插入具有重复_id值的文档时，驱动程序会抛出BulkWriteError。然而，驱动程序仍然在错误发生之前插入文档。
如果您传递值为false，则在尝试插入具有重复_id值的文档时，驱动程序仍然会抛出BulkWriteError，但它会插入其他所有文档。

以下代码演示了如何执行无序写入操作来插入前面的文档

let docs = vec![
    Book { _id: 1, title: "Where the Wild Things Are".to_string(), author: "".to_string() },
    Book { _id: 2, title: "The Very Hungry Caterpillar".to_string(), author: "".to_string() },
    Book { _id: 1, title: "Blueberries for Sal".to_string(), author: "".to_string() },
    Book { _id: 3, title: "Goodnight Moon".to_string(), author: "".to_string() }
];
my_coll.insert_many(docs).ordered(false).await?;

尽管此操作导致BulkWriteError，您仍然可以在您的集合中找到非错误生成文档

{ "_id": 1, "title": "Where the Wild Things Are" }
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
{ "_id": 3, "title": "Goodnight Moon" }

概述

字段 _id

重要

重复的 _id 值

插入文档

示例

提示

不存在的数据库和集合

修改 insert_one 的行为

注意

设置选项

插入多个文档

示例

提示

不存在的数据库和集合

修改 insert_many 行为

有序行为示例

更多信息

API 文档