批量写入操作

Overview

在本指南中，您可以学习；了解如何使用批量写入操作在单个数据库调用中执行多个写入操作。

考虑这样一种情况：您想要将一个文档插入到一个集合中，更新多个其他文档，然后删除一个文档。如果使用单个函数，则每个操作都需要调用自己的数据库。相反，您可以使用批量操作来减少对数据库的调用次数。

样本数据

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.

启动批量写入操作

在运行批量写入操作之前，请调用 mongoc_collection_create_bulk_operation_with_opts() 函数。此函数返回一个类型为 mongoc_bulk_operation_t 的值，您可以使用该值存储有关要执行哪些批量写入的指令。

mongoc_collection_create_bulk_operation_with_opts() 函数接受以下参数：

Collection ：指定要修改的集合
选项文档：指定用于自定义操作的选项，或NULL

以下示例调用 mongoc_collection_create_bulk_operation_with_opts() 函数并将 restaurants集合作为参数传递：

mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);

然后，您可以向批量操作添加写入指令。有关更多信息，请参阅下面的“定义写入操作”部分。

定义写入操作

您可以通过调用以下方法定义写入操作并将其添加到批量写入中：

mongoc_bulk_operation_insert_with_opts()
mongoc_bulk_operation_update_one_with_opts()
mongoc_bulk_operation_update_many_with_opts()
mongoc_bulk_operation_replace_one_with_opts()
mongoc_bulk_operation_remove_one_with_opts()
mongoc_bulk_operation_remove_many_with_opts()

以下部分介绍如何使用这些方法来指定相应的写入。

插入操作

要执行插入操作，请将插入指令添加到 mongoc_bulk_operation_t，该操作将作为批量写入的一部分对该操作进行排队。

以下示例调用 mongoc_bulk_operation_insert_with_opts() 函数，将要插入的文档和 mongoc_bulk_operation_t 值作为参数传递：

bson_t *insert_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches"),
    "borough", BCON_UTF8("Manhattan"),
    "restaurant_id", BCON_UTF8("1234")
);
bson_error_t error;
if (!mongoc_bulk_operation_insert_with_opts(bulk, insert_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add insert operation: %s\n", error.message);
}
bson_destroy(insert_doc);

要插入多个文档，请为每个文档调用 mongoc_bulk_operation_insert_with_opts()。

更新操作

要执行更新操作，请将更新指令添加到 mongoc_bulk_operation_t，该操作将作为批量写入的一部分对该操作进行排队。

以下示例调用 mongoc_bulk_operation_update_one_with_opts() 函数，将查询过滤、文档更新和 mongoc_bulk_operation_t 值作为参数传递：

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_one_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

要更新多个文档，请调用 mongoc_bulk_operation_update_many_with_opts() 并传入相同的参数。这会指示驱动程序更新与查询筛选条件匹配的所有文档。

以下示例将对批量写入的更新多次操作进行排队：

bson_t *filter_doc = BCON_NEW("name", BCON_UTF8("Mongo's Deli"));
bson_t *update_doc = BCON_NEW("$set", "{", "cuisine", BCON_UTF8("Sandwiches and Salads"), "}");
bson_error_t error;
if (!mongoc_bulk_operation_update_many_with_opts(bulk, filter_doc, update_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add update operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(update_doc);

替换操作

替换操作会删除指定文档的所有字段和值，然后替换为新的字段和值。要执行替换操作，请将替换指令添加到 mongoc_bulk_operation_t，该操作将作为批量写入的一部分对该操作进行排队。

以下示例调用 mongoc_bulk_operation_replace_one_with_opts() 函数，将查询过滤、替换文档和 mongoc_bulk_operation_t 值作为参数传递：

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("1234"));
bson_t *replace_doc = BCON_NEW(
    "name", BCON_UTF8("Mongo's Deli"),
    "cuisine", BCON_UTF8("Sandwiches and Salads"),
    "borough", BCON_UTF8("Brooklyn"),
    "restaurant_id", BCON_UTF8("5678")
);
bson_error_t error;
if (!mongoc_bulk_operation_replace_one_with_opts(bulk, filter_doc, replace_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add replace operation: %s\n", error.message);
}
bson_destroy(filter_doc);
bson_destroy(replace_doc);

要替换多个文档，请为每个文档调用 mongoc_bulk_operation_replace_one_with_opts()。

删除操作

要执行删除操作，请将删除指令添加到 mongoc_bulk_operation_t 中，该操作将作为批量写入的一部分对该操作进行排队。

以下示例调用 mongoc_bulk_operation_remove_one_with_opts() 函数，将查询过滤和 mongoc_bulk_operation_t 值作为参数传递：

bson_t *filter_doc = BCON_NEW("restaurant_id", BCON_UTF8("5678"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_one_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

要删除多个文档，请调用 mongoc_bulk_operation_remove_many_with_opts() 函数并传入相同的参数。这会指示驱动程序删除与查询筛选条件匹配的所有文档。

以下示例将删除多个操作排队到批量写入：

bson_t *filter_doc = BCON_NEW("borough", BCON_UTF8("Manhattan"));
bson_error_t error;
if (!mongoc_bulk_operation_remove_many_with_opts(bulk, filter_doc, NULL, &error)) {
    fprintf(stderr, "Failed to add delete operation: %s\n", error.message);
}
bson_destroy(filter_doc);

运行批量操作

要运行批量写入中排队的每个写入操作，请调用 mongoc_bulk_operation_execute() 函数。此函数接受以下参数：

mongoc_bulk_operation_t value ：包含每个写入操作的指令
结果位置：指定指向将包含操作结果的可覆盖存储的指针，或NULL
错误位置：指定错误值的位置，或NULL

使用以下语法批量写入文档：

bson_error_t error;
mongoc_bulk_operation_t *bulk =
   mongoc_collection_create_bulk_operation_with_opts(collection, NULL);
bson_t *insert_doc = BCON_NEW(
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>"),
    "<field name>", BCON_UTF8("<value>")
);
mongoc_bulk_operation_insert(bulk, insert_doc);
bson_destroy(insert_doc);
    
bson_t *query = BCON_NEW("<field to match>", BCON_UTF8("<value to match>"));
bson_t *update = BCON_NEW("$set", "{", "<field name>", BCON_UTF8("<value>"), "}");
mongoc_bulk_operation_update_one(bulk, query, update, false);
bson_destroy(query);
bson_destroy(update);
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    fprintf(stderr, "Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

以下示例通过调用 mongoc_bulk_operation_execute()函数执行本指南前面部分中指定的插入、更新、替换和删除操作：

bson_error_t error;
bool result = mongoc_bulk_operation_execute(bulk, NULL, &error);
if (!result) {
    printf("Bulk operation error: %s\n", error.message);
}
mongoc_bulk_operation_destroy(bulk);

如果任何写入操作失败， C驱动程序将设置输出错误并且不会执行任何进一步的操作。

自定义批量写入操作

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

选项	说明
`ordered`	如果 `true`，则驱动程序会按照提供的顺序执行写入操作。如果发生错误，则不会尝试其他操作。如果 `false`，则驱动程序会以任意顺序执行操作，并尝试执行所有操作。默认为 `true`。
`writeConcern`	指定批量操作的写关注（write concern）。有关更多信息，请参阅MongoDB Server手册中的写关注。
`sessionId`	在指定的会话中运行批量操作。有关详细信息，请参阅 MongoDB Server 手册中的服务器会话。
`comment`	为操作附加注释。有关更多信息，请参阅MongoDB Server手册中的删除命令字段指南。
`let`	指定包含值列表的文档，以提高操作的可读性。值必须是常量或不引用文档字段的闭合表达式。有关更多信息，请参阅MongoDB Server手册中的 let声明。

以下示例调用 mongoc_collection_create_bulk_operation_with_opts() 函数并将 ordered 选项设置为 false：

bson_t opts;
BSON_APPEND_BOOL(&opts, "ordered", false);
bulk = mongoc_collection_create_bulk_operation_with_opts(collection, &opts);
// Perform bulk operation
bson_destroy(&opts);
mongoc_bulk_operation_destroy(bulk);

如果无序批量写入中的任何写入操作失败， C驱动程序仅在尝试所有操作后才会报告错误。

注意

无序批量操作不保证执行顺序。为了优化运行时间，顺序可以与您列出的方式不同。