批量写入操作

在此页面上

Overview

样本数据
启动批量写入操作
定义写入操作
插入操作
更新操作
替换操作
删除操作
运行批量操作
自定义批量写入操作
更多信息
API 文档

Overview

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

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

样本数据

本指南中的示例使用 Atlas示例数据集的sample_restaurants数据库中的 restaurants集合。要学习；了解如何创建免费的MongoDB Atlas 群集并加载示例数据集，请参阅Atlas入门指南。

启动批量写入操作

在运行批量写入操作之前，请调用 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

以下示例通过调用 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`	If `true`, the driver performs the write operations in the order provided. If an error occurs, the remaining operations are not attempted. If `false`, the driver performs the operations in an arbitrary order and attempts to perform all operations. Defaults to `true`.
`writeConcern`	Specifies the write concern for the bulk operation. For more information, see Write Concern in the MongoDB Server manual.
`sessionId`	Runs the bulk operations within the specified session. For more information, see Server Sessions in the MongoDB Server manual.
`comment`	Attaches a comment to the operation. For more information, see the delete command fields guide in the MongoDB Server manual.
`let`	Specifies a document with a list of values to improve operation readability. Values must be constant or closed expressions that don't reference document fields. For more information, see the let statement in the MongoDB Server manual.

以下示例调用 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驾驶员仅在尝试所有操作后才会报告错误。

注意

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