对于 AI 代理:可在 https://www.mongodb.com/zh-cn/docs/llms.txt 获取文档索引—通过在任何 URL 路径后添加 .md 可获取所有页面的 Markdown 版本。

插入文档

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

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

  • insert_one() 插入一个文档

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

本指南包括以下部分:

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

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

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

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

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

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

重要

重复 _id 值

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

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

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

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

您必须插入与参数化Collection实例相同类型的文档。 例如,如果使用MyStruct MyStruct结构对collection进行了参数化,请将instance作为参数传递给insert_one() 方法以插入文档。要了解有关指定类型参数的更多信息,请参阅数据库和collection指南中的collection参数化部分。

插入成功后,该方法将返回一个 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);

提示

不存在的数据库和集合

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

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

注意

设置选项

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

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

选项
说明

bypass_document_validation

如果为 true,允许驱动程序执行违反文档级验证的写入。要了解有关验证的更多信息,请参阅有关模式验证的指南。

类型:bool
默认:false

write_concern

操作的写关注(write concern)。如果您未设置此选项,则操作会继承为集合设置的写关注(write concern)。要了解有关写关注(write concern)的更多信息,请参阅服务器手册中的写关注(write concern)。

类型:WriteConcern

comment

与操作绑定的任意 Bson 值,可通过数据库分析器、currentOp 和日志进行追踪。此选项仅在连接到 MongoDB Server 4.4 及更高版本时可用。

类型:Bson
默认:None

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

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

此示例将文档插入到 sample_restaurants数据库的 restaurants集合中。 insert_one() 方法插入具有 name、borough 和 cuisine字段值的文档。

您可以将此文档作为 Document 类型或自定义数据类型的实例插入。 要指定代表集合数据的数据类型,请对突出显示的行执行以下操作:

  • 要访问权限集合文档并将其作为BSON文档插入,请将 <T> 类型参数替换为 <Document>,并将 <struct or doc> 占位符替换为 insert_doc。

  • 要访问权限集合文档并将其作为 Restaurant 结构体的实例插入,请将 <T> 类型参数替换为 <Restaurant>,并将 <struct or doc> 占位符替换为 insert_struct。 Restaurant 结构体在代码文件的顶部定义。

选择Asynchronous或Synchronous标签页,查看每个运行时的相应代码:

use std::env;use mongodb::{ bson::{doc, Document}, Client, Collection };use serde::{ Deserialize, Serialize }; #[derive(Serialize, Deserialize, Debug)]struct Restaurant { borough: String, cuisine: String, name: String,} #[tokio::main]async fn main() -> mongodb::error::Result<()> { let uri = "<connection string>"; let client = Client::with_uri_str(uri).await?; // Replace <T> with the <Document> or <Restaurant> type parameter let my_coll: Collection<T> = client .database("sample_restaurants") .collection("restaurants"); let insert_doc = doc! { "name": "Sea Stone Tavern", "cuisine": "Greek", "borough": "Queens", }; let insert_struct = Restaurant { name: "Sea Stone Tavern".to_string(), cuisine: "Greek".to_string(), borough: "Queens".to_string(), }; // Replace <struct or doc> with the insert_struct or insert_doc variable let res = my_coll.insert_one(<struct or doc>).await?; println!("Inserted a document with _id: {}", res.inserted_id); Ok(())}

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

将包含一个或多个文档的向量传递给insert_many()方法,以将它们插入到collection中。这些文档必须是您参数化Collection实例时使用的类型的实例。 例如,如果使用 结构对collection进行了参数化,请将实例向量作为参数传递给MyStruct MyStructinsert_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);}

提示

不存在的数据库和集合

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

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

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

选项
说明

bypass_document_validation

如果为 true,允许驱动程序执行违反文档级验证的写入。要了解有关验证的更多信息,请参阅有关模式验证的指南。

类型:bool
默认:false

ordered

如果为 true,则当任何插入失败时,操作都会返回而不插入剩余文档。如果为 false,即使插入失败,操作也会继续执行剩余的写入操作。要学习;了解有关有序插入的更多信息,请参阅本指南的有序行为示例部分。

类型:bool
默认:true

write_concern

操作的写关注(write concern)。如果您未设置此选项,则操作会继承为集合设置的写关注(write concern)。要了解有关写关注(write concern)的更多信息,请参阅服务器手册中的写关注(write concern)。

类型:WriteConcern

comment

与操作绑定的任意 Bson 值,可通过数据库分析器、currentOp 和日志进行追踪。此选项仅在连接到 MongoDB Server 4.4 及更高版本时可用。

类型:Bson
默认:None

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

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

此示例将多个文档插入到 sample_restaurants数据库的 restaurants集合中。 该示例通过将文档向量传递给 insert_many() 方法来插入具有 name 和 cuisine字段值的文档。

您可以将这些文档作为 Document 类型或自定义数据类型的实例插入。 要指定代表集合数据的数据类型,请对突出显示的行执行以下操作:

  • 要访问权限集合文档并将其作为BSON文档插入,请将 <T> 类型参数替换为 <Document>,并将 <struct or doc> 占位符替换为 insert_docs。

  • 要访问权限集合文档并将其作为 Restaurant 结构体的实例插入,请将 <T> 类型参数替换为 <Restaurant>,并将 <struct or doc> 占位符替换为 insert_structs。 Restaurant 结构体在代码文件的顶部定义。

选择Asynchronous或Synchronous标签页,查看每个运行时的相应代码:

use mongodb::{ bson::{doc, Document}, Client, Collection };use serde::{ Deserialize, Serialize }; #[derive(Serialize, Deserialize, Debug)]struct Restaurant { name: String, cuisine: String,} #[tokio::main]async fn main() -> mongodb::error::Result<()> { let uri = "<connection string>"; let client = Client::with_uri_str(uri).await?; // Replace <T> with the <Document> or <Restaurant> type parameter let my_coll: Collection<T> = client .database("sample_restaurants") .collection("restaurants"); let insert_docs = vec! [ doc! { "name": "While in Kathmandu", "cuisine": "Nepalese", }, doc! { "name": "Cafe Himalaya", "cuisine": "Nepalese", } ]; let insert_structs = vec! [ Restaurant { name: "While in Kathmandu".to_string(), cuisine: "Nepalese".to_string(), }, Restaurant { name: "Cafe Himalaya".to_string(), cuisine: "Nepalese".to_string(), } ]; // Replace <structs or docs> with the insert_structs or insert_docs variable let insert_many_result = my_coll.insert_many(<structs or docs>).await?; println!("Inserted documents with _ids:"); for (_key, value) in &insert_many_result.inserted_ids { println!("{}", value); } Ok(())}

假设您要将以下文档插入到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 文档: