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

插入文档

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

在 MongoDB 中查找、更新和删除文档之前,必须先插入这些文档。您可以使用 InsertOne() 方法插入一个文档,也可以使用 InsertMany() 或 BulkWrite() 方法插入多个文档。

以下各部分重点介绍 InsertOne() 和 InsertMany()。要了解如何使用 BulkWrite() 方法,请参阅批量操作指南。

在 MongoDB 中,每个文档都必须包含一个唯一的 _id 字段。

管理这个字段的两个选项是:

  • 自行管理此字段,确保使用的每个值都是唯一的。

  • 让驱动程序自动生成唯一的 ObjectId 值。驱动程序会为您未明确指定 _id 的文档生成唯一的 ObjectId 值。

除非为唯一性提供强有力的保证,否则,MongoDB 建议让驱动程序自动生成 _id 值。

注意

重复的 _id 值违反了唯一索引约束,导致驱动程序返回 WriteError。

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

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

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

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

此示例使用以下 Book 结构作为 books 集合中文档的模型:

type Book struct { Title string Author string}

以下示例将使用 InsertOne() 方法来创建文档并将其插入到 books 集合:

coll := client.Database("db").Collection("books")doc := Book{Title: "Atonement", Author: "Ian McEwan"} result, err := coll.InsertOne(context.TODO(), doc) fmt.Printf("Inserted document with _id: %v\n", result.InsertedID)

您可以通过构造和传递可选InsertOneOptions结构来修改 InsertOne() 的行为。使用InsertOneOptions设置的可用选项有:

选项
说明

BypassDocumentValidation

如果为 true,则允许写入选择退出文档级验证。

默认: false

构造一个InsertOneOptions,如下所示:

opts := options.InsertOne().SetBypassDocumentValidation(true)

注意

设置示例

该示例使用连接 URI 连接到 MongoDB 实例。如需了解有关连接到 MongoDB 实例的更多信息,请参阅创建 MongoClient。本示例还使用了Atlas 示例数据集中包含的 sample_restaurants 数据库中的 restaurants 集合。您可以按照Atlas 入门指南中的步骤,将它们加载到 MongoDB Atlas 免费集群上的数据库中。

以下示例将新文档插入 restaurants集合。选择Struct或bson.D标签页以查看相应的代码:

以下代码使用结构体将新文档插入到 restaurants集合中:

// Inserts a single document describing a restaurant by using the Go driverpackage main import ( "context" "fmt" "log" "os" "github.com/joho/godotenv" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options") // Defines the structure of a restaurant documenttype Restaurant struct { Name string RestaurantId string `bson:"restaurant_id,omitempty"` Cuisine string `bson:"cuisine,omitempty"` Address any `bson:"address,omitempty"` Borough string `bson:"borough,omitempty"` Grades []any `bson:"grades,omitempty"`} func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") } var uri string if uri = os.Getenv("MONGODB_URI"); uri == "" { log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/zh-cn/docs/drivers/go/current/connect/mongoclient/#environment-variable") } client, err := mongo.Connect(options.Client().ApplyURI(uri)) if err != nil { panic(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { panic(err) } }() // Inserts a sample document describing a restaurant into the collection coll := client.Database("sample_restaurants").Collection("restaurants") newRestaurant := Restaurant{Name: "8282", Cuisine: "Korean"} result, err := coll.InsertOne(context.TODO(), newRestaurant) if err != nil { panic(err) } // Prints the ID of the inserted document fmt.Printf("Document inserted with ID: %s\n", result.InsertedID) // When you run this file for the first time, it should print output similar // to the following: // Document inserted with ID: ObjectID("...") }

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

插入成功后,InsertMany() 方法会返回一个 InsertManyResult 实例,其中包含已插入文档的 _id 字段。

下面的示例使用 InsertMany() 方法在 books 集合中创建并插入多个文档:

coll := client.Database("myDB").Collection("favorite_books")docs := []any{ Book{Title: "Cat's Cradle", Author: "Kurt Vonnegut Jr."}, Book{Title: "In Memory of Memory", Author: "Maria Stepanova"}, Book{Title: "Pride and Prejudice", Author: "Jane Austen"},} result, err := coll.InsertMany(context.TODO(), docs)fmt.Printf("Documents inserted: %v\n", len(result.InsertedIDs)) for _, id := range result.InsertedIDs { fmt.Printf("Inserted document with _id: %v\n", id)}

运行上述代码后,输出结果如下:

Documents inserted: 3Inserted document with _id: ObjectID("...")Inserted document with _id: ObjectID("...")Inserted document with _id: ObjectID("...")

您可以通过构造和传递可选InsertManyOptions结构来修改 InsertMany() 的行为。使用InsertManyOptions设置的可用选项有:

选项
说明

BypassDocumentValidation

如果为 true,则允许写入选择退出文档级验证。

默认: false

Ordered

如果为 true,则驱动程序按照规定的顺序向服务器发送文档。如果发生错误,驱动程序和服务器会中止所有剩余的插入操作。要了解更多信息,请参阅有序行为。

默认: false

构造一个InsertManyOptions,如下所示:

opts := options.InsertMany().SetBypassDocumentValidation(true).SetOrdered(false)

假设要插入以下文档:

{ "_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" }

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

注意

即使发生 BulkWriteException,也可获得文档插入成功的确认:

type Book struct { ID int `bson:"_id"` Title string} ... docs := []any{ Book{ID: 1, Title: "Where the Wild Things Are"}, Book{ID: 2, Title: "The Very Hungry Caterpillar"}, Book{ID: 1, Title: "Blueberries for Sal"}, Book{ID: 3, Title: "Goodnight Moon"},} result, err := coll.InsertMany(context.TODO(), docs)if err != nil { fmt.Printf("A bulk write error occurred, but %v documents were still inserted.\n", len(result.InsertedIDs))} for _, id := range result.InsertedIDs { fmt.Printf("Inserted document with _id: %v\n", id)}

运行上述代码后,您的集合将包含以下文档:

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

注意

设置示例

该示例使用连接 URI 连接到 MongoDB 实例。如需了解有关连接到 MongoDB 实例的更多信息,请参阅创建 MongoClient。本示例还使用了Atlas 示例数据集中包含的 sample_restaurants 数据库中的 restaurants 集合。您可以按照Atlas 入门指南中的步骤,将它们加载到 MongoDB Atlas 免费集群上的数据库中。

以下示例将多个新文档插入到 restaurants集合中。选择Struct或bson.D标签页以查看相应的代码:

以下代码使用结构体将多个新文档插入到 restaurants集合中:

// Inserts sample documents describing restaurants by using the Go driverpackage main import ( "context" "fmt" "log" "os" "github.com/joho/godotenv" "go.mongodb.org/mongo-driver/v2/mongo" "go.mongodb.org/mongo-driver/v2/mongo/options") // Defines the structure of a restaurant documenttype Restaurant struct { Name string RestaurantId string `bson:"restaurant_id,omitempty"` Cuisine string `bson:"cuisine,omitempty"` Address any `bson:"address,omitempty"` Borough string `bson:"borough,omitempty"` Grades []any `bson:"grades,omitempty"`} func main() { if err := godotenv.Load(); err != nil { log.Println("No .env file found") } var uri string if uri = os.Getenv("MONGODB_URI"); uri == "" { log.Fatal("You must set your 'MONGODB_URI' environment variable. See\n\t https://www.mongodb.com/zh-cn/docs/drivers/go/current/connect/mongoclient/#environment-variable") } client, err := mongo.Connect(options.Client().ApplyURI(uri)) if err != nil { panic(err) } defer func() { if err = client.Disconnect(context.TODO()); err != nil { panic(err) } }() coll := client.Database("sample_restaurants").Collection("restaurants") // Creates two sample documents describing restaurants newRestaurants := []any{ Restaurant{Name: "Rule of Thirds", Cuisine: "Japanese"}, Restaurant{Name: "Madame Vo", Cuisine: "Vietnamese"}, } // Inserts sample documents into the collection result, err := coll.InsertMany(context.TODO(), newRestaurants) if err != nil { panic(err) } // Prints the IDs of the inserted documents fmt.Printf("%d documents inserted with IDs:\n", len(result.InsertedIDs)) for _, id := range result.InsertedIDs { fmt.Printf("\t%s\n", id) } // When you run this file for the first time, it should print output similar // to the following: // 2 documents inserted with IDs: // ObjectID("...") // ObjectID("...")}

要了解有关执行上述操作的更多信息,请参阅以下指南:

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