插入文档

Overview

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

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

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

_id 字段

在 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)

Inserted document with _id: ObjectID("...")

修改 InsertOne() 行为

您可以通过构造和传递可选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 driver
package 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 document
type 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("...")
}

Document inserted with ID: ObjectID("...")

以下代码使用 bson.D 类型将新文档插入到 restaurants集合中：

// Inserts a single document describing a restaurant by using the Go driver with bson.D
package main
import (
	"context"
	"fmt"
	"log"
	"os"
	"github.com/joho/godotenv"
	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
	"go.mongodb.org/mongo-driver/v2/mongo/options"
)
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 using bson.D
	coll := client.Database("sample_restaurants").Collection("restaurants")
	newRestaurant := bson.D{
		bson.E{Key: "name", Value: "8282"},
		bson.E{Key: "cuisine", Value: "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("...")
}

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: 3
Inserted document with _id: ObjectID("...")
Inserted document with _id: ObjectID("...")
Inserted document with _id: ObjectID("...")

修改 InsertMany() 行为

您可以通过构造和传递可选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)
}

A bulk write error occurred, but 2 documents were still inserted.
Inserted document with _id: 1
Inserted document with _id: 2

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

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

插入多个示例：完整文件

注意

设置示例

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

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

// Inserts sample documents describing restaurants by using the Go driver
package 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 document
type 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("...")
}

2 documents inserted with IDs:
        ObjectID("...")
        ObjectID("...")

以下代码使用 bson.D 类型将多个新文档插入到 restaurants集合中：

// Inserts sample documents describing restaurants by using the Go driver with bson.D
package main
import (
	"context"
	"fmt"
	"log"
	"os"
	"github.com/joho/godotenv"
	"go.mongodb.org/mongo-driver/v2/bson"
	"go.mongodb.org/mongo-driver/v2/mongo"
	"go.mongodb.org/mongo-driver/v2/mongo/options"
)
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 using bson.D
	newRestaurants := []interface{}{
		bson.D{
			bson.E{Key: "name", Value: "Rule of Thirds"},
			bson.E{Key: "cuisine", Value: "Japanese"},
		},
		bson.D{
			bson.E{Key: "name", Value: "Madame Vo"},
			bson.E{Key: "cuisine", Value: "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("...")
}

2 documents inserted with IDs:
        ObjectID("...")
        ObjectID("...")

插入文档

Overview

_id 字段

注意

插入文档

例子

修改 InsertOne() 行为

插入文档示例：完整文件

注意

设置示例

插入多个文档

例子

修改 InsertMany() 行为

有序行为

注意

插入多个示例：完整文件

注意

设置示例

更多信息

API 文档