插入文档

Overview

在本指南中，您可以学习如何使用C驱动程序通过执行插入操作将文档添加到MongoDB集合。

插入操作将一个或多个文档插入MongoDB集合。您可以使用以下函数执行插入操作：

mongoc_collection_insert_one() 插入单个文档的函数
mongoc_collection_insert_many() 函数插入一个或多个文档

样本数据

The examples in this guide use the restaurants collection in the sample_restaurants database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the MongoDB Get Started guide.

_id 字段

在 MongoDB 集合中，每个文档必须包含具有唯一字段值的 _id 字段。

MongoDB 允许您通过两种方式管理该字段：

自行为每个文档设置_id字段，确保每个值都是唯一的。
让驱动程序自动为每个文档_id字段生成唯一的 bson_oid_t 值。

除非您可以保证唯一性，否则我们建议让驱动程序自动生成_id值。

注意

重复的 _id 值违反了唯一索引约束，导致驱动程序返回 mongoc_bulkwriteexception_t 错误。

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

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

插入一个文档

要将单个文档添加到MongoDB集合，请调用 mongoc_collection_insert_one() 函数并传递以下参数：

要在其中插入文档的集合
要插入的文档
用于自定义操作的选项，或 NULL
指向将包含操作结果的可重写存储的指针，或 NULL
错误值的位置，或 NULL

使用以下语法插入文档：

bson_t *document = BCON_NEW("<field name>", BCON_UTF8("<value>"));
bson_error_t error;
if (!mongoc_collection_insert_one(
    collection, document, NULL, NULL, &error)) {
    fprintf(stderr, "Insert one operation failed: %s\n", error.message);
}
bson_destroy(document);

以下示例将文档插入restaurants集合：

bson_t *document = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
bson_error_t error;
if (!mongoc_collection_insert_one(collection, document, NULL, NULL, &error)) {
    fprintf(stderr, "Insert one operation failed: %s\n", error.message);
}
bson_destroy(document);

插入多个文档

要将多个文档添加到MongoDB集合，请调用 mongoc_collection_insert_many() 函数并传递以下参数：

要在其中插入文档的集合
指向要插入的文档的指针数组
要插入的文档数
用于自定义操作的选项，或 NULL
指向将包含操作结果的可重写存储的指针，或 NULL
错误值的位置，或 NULL

使用以下语法插入多个文档：

size_t num_docs = 2;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("<field name>", BCON_UTF8("<value>"));
docs[1] = BCON_NEW("<field name>", BCON_UTF8("<value>"));
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, NULL, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);

以下示例将两个文档插入restaurants集合：

size_t num_docs = 2;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
docs[1] = BCON_NEW("name", BCON_UTF8("Mongo's Pizza"));
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, NULL, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);

修改插入行为

您可以通过传递指定选项值的BSON文档来修改 mongoc_collection_insert_one() 和 mongoc_collection_insert_many() 函数的行为。下表描述了您可以在文档中设立的一些选项：

选项	说明
`bypassDocumentValidation`	如果设置为 `true`，则允许写入操作选择退出文档级验证。默认为 `false`。类型：`bool`
`writeConcern`	设置操作的写关注（write concern）。默认为命名空间的写关注（write concern）。类型：`mongoc_write_concern_t`
`ordered`	如果设置为 `true`，则当一个插入失败时，操作会停止插入文档。如果 `false`，则当一个插入失败时，操作会继续插入剩余文档。您不能将此选项传递给 `mongoc_collection_insert_one()` 函数。默认为 `true`。类型：`bool`
`comment`	附加到操作的评论。有关详细信息，请参阅 MongoDB Server 手册中的插入命令字段指南。类型：`bson_value_t`

例子

以下代码使用 mongoc_collection_insert_many() 函数将三个新文档插入到集合中。由于 bypassDocumentValidation字段设立为 true，因此此插入操作会绕过文档级验证：

size_t num_docs = 3;
bson_t *docs[num_docs];
docs[0] = BCON_NEW("name", BCON_UTF8("Mongo's Burgers"));
docs[1] = BCON_NEW("name", BCON_UTF8("Mongo's Pizza"));
docs[2] = BCON_NEW("name", BCON_UTF8("Mongo's Tacos"));
bson_t opts;
bson_init(&opts);
bson_append_bool(&opts, "bypassDocumentValidation", -1, true);
bson_error_t error;
if (!mongoc_collection_insert_many(collection, (const bson_t **) docs, num_docs, &opts, NULL, &error)) {
    fprintf(stderr, "Insert many operation failed: %s\n", error.message);
}
bson_destroy(docs[0]);
bson_destroy(docs[1]);
bson_destroy(docs[2]);
bson_destroy(&opts);