Docs 菜单
Docs 主页
/
语言
/
Rust
/
Rust 驱动程序
/
Fundamentals
/
CRUD
/
写入

插入文档

在此页面上

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

Overview

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

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

  • insert_one() 插入一个文档

  • insert_many() 插入一个或多个文档

本指南包括以下部分：

  • _id 字段描述每个文档包含的_id字段

  • 插入文档描述了如何使用驱动程序将单个文档插入到集合中

  • 插入多个文档描述了如何使用驱动程序将多个文档插入到集合中

  • 附加信息提供了本指南中提到的类型和方法的资源和 API 文档链接

_id 字段

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

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

重要

重复 _id 值

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

要了解有关_id 字段的更多信息，请参阅 MongoDB Server手册中的 唯一索引 。

要了解有关文档结构和规则的更多信息，请参阅 MongoDB Server手册中的 文档 。

插入文档

使用 insert_one() 方法向集合插入多个文档。

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

例子

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

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

提示

不存在的数据库和集合

如果对数据库和collection执行写入操作时不存在，服务器会自动创建它们。

修改 insert_one 行为

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

注意

设置选项

您可以通过将选项构建器方法直接链接到insert_one()方法调用来设立InsertOneOptions字段。 如果使用的是早期版本的驾驶员，则必须通过将选项构建器方法链接到builder()方法来构造InsertOneOptions实例。 然后，将选项实例作为参数传递给insert_one() 。

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

选项
说明

bypass_document_validation

If true, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation.

Type: bool
Default: false

write_concern

The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual.

Type: WriteConcern

comment

An arbitrary Bson value tied to the operation to trace it through the database profiler, currentOp, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later.

Type: Bson
Default: None

以下代码展示了如何通过将bypass_document_validation()方法链接到insert_one()方法来设立bypass_document_validation字段：

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

插入多个文档

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

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

例子

以下示例使用insert_many()方法将多个文档插入到bookscollection中：

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)

提示

不存在的数据库和集合

如果对数据库和collection执行写入操作时不存在，服务器会自动创建它们。

修改 insert_many 行为

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

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

选项
说明

bypass_document_validation

If true, allows the driver to perform a write that violates document-level validation. To learn more about validation, see the guide on Schema Validation.

Type: bool
Default: false

ordered

If true, when any insert fails, the operation returns without inserting the remaining documents. If false, even if an insert fails, the operation continues with the remaining writes. To learn more about ordered inserts, see the Ordered Behavior Example section of this guide.

Type: bool
Default: true

write_concern

The write concern for the operation. If you don't set this option, the operation inherits the write concern set for the collection. To learn more about write concerns, see Write Concern in the Server manual.

Type: WriteConcern

comment

An arbitrary Bson value tied to the operation to trace it through the database profiler, currentOp, and logs. This option is available only when connecting to MongoDB Server versions 4.4 and later.

Type: Bson
Default: None

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

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

有序行为示例

假设您要将以下文档插入到bookscollection中：

{ "_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 ，您仍然可以在collection中找到未出错的文档：

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

更多信息

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

API 文档

要进一步了解本指南所提及的方法和类型，请参阅以下 API 文档：

后退

写入

来年

Modify