MONGOC_COLLECTION_UPDATE_ONE(3)

💖 MONGOC_COLLECTION_UPDATE_ONE(3) 💖

okay so bestie, this is the libmongoc glow-up page for mongoc_collection_update_one — the function that goes in and edits one little document for you. no cap, it's giving "surgical queen" energy 🎀 and we're gonna walk through every single flag together, so grab a strawberry drink and let's go ✨

---

🌸 SYNOPSIS 🌸

bool
mongoc_collection_update_one (mongoc_collection_t *collection,
                              const bson_t *selector,
                              const bson_t *update,
                              const bson_t *opts,
                              bson_t *reply,
                              bson_error_t *error);

---

🦋 PARAMETERS 🦋

• collection — a mongoc_collection_t. that's your collection, your main character 🫶
• selector — a bson_t holding the query that matches which document gets updated 🔍
• update — a bson_t with the update to perform. and listen: if you're updating with a pipeline, this is a bson_t array, iykyk 💅
• reply — a maybe-NULL pointer to overwritable storage for a bson_t that'll hold the results 📬
• error — an optional location for a bson_error_t, or NULL. optional! no pressure 🙈

and then opts — it may be NULL, or a BSON document with extra command options. here's the whole menu, bestie:

• writeConcern — construct a mongoc_write_concern_t and use mongoc_write_concern_append() to add the write concern to opts. see the example code for mongoc_client_write_command_with_opts() ✨
• sessionId — first, construct a mongoc_client_session_t with mongoc_client_start_session(). you can begin a transaction with mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that overrides the options inherited from collection, and use mongoc_client_session_append() to add the session to opts. see the example code for mongoc_client_session_t 🧚
• validate — construct a bitwise-or of all desired bson_validate_flags_t. set it to false to skip client-side validation of the provided BSON documents 🚫
• comment — a bson_value_t specifying the comment to attach to this command. the comment will appear in log messages, profiler output, and currentOp output. requires MongoDB 4.4 or later 📝
• bypassDocumentValidation — set to true to skip server-side schema validation of the provided BSON documents 🏃‍♀️
• collation — configure textual comparisons. see Setting Collation Order, and the MongoDB Manual entry on Collation. collation requires MongoDB 3.2 or later, otherwise an error is returned ⚠️
• hint — a document or string that specifies the index to use to support the query predicate 💡
• upsert — when true, creates a new document if no document matches the query 🌱
• let — a BSON document consisting of any number of parameter names, each followed by definitions of constants in the MQL Aggregate Expression language 🔤
• arrayFilters — an array of filters specifying to which array elements an update should apply 🎯
• sort — specify a sort order when matching documents 🔀

---

👑 DESCRIPTION 👑

this function updates at most one document in collection that matches selector. one. single. document. it's picky and we respect it 💅

wanna update multiple documents instead? that's mongoc_collection_update_many(), different vibes, different function 🦋

if you pass a non-NULL reply, it gets filled out with the fields matchedCount, modifiedCount, and optionally upsertedId if applicable. but if there's a server error then reply contains either a "writeErrors" array with one subdocument or a "writeConcernErrors" array 😭 and — important — the reply must be freed with bson_destroy(). don't leave it hanging, bestie 🫶

---

💀 ERRORS 💀

errors are propagated via the error parameter. that's the whole tea ☕

---

🌈 RETURNS 🌈

returns true if successful. returns false and sets error if there are invalid arguments or a server or network error 😔

and a write concern timeout or write concern error is considered a failure. fr fr, that counts as a fail 💔

---

🍓 EXAMPLE 🍓

example-update.c:

#include <mongoc/mongoc.h>

int
main(void)
{
   mongoc_init();
   bson_t *to_insert = BCON_NEW("_id", BCON_INT32(1));
   bson_t *selector = BCON_NEW("_id", "{", "$gt", BCON_INT32(0), "}");
   bson_t *update = BCON_NEW("$set", "{", "x", BCON_INT32(1), "}");
   const bson_t *next_doc;
   char *to_str;
   bson_error_t error = {0};
   mongoc_cursor_t *cursor;
   mongoc_client_t *client;
   mongoc_collection_t *coll;
   const char *uri_string = "mongodb://localhost:27017/?appname=example-update";
   mongoc_uri_t *uri = mongoc_uri_new_with_error(uri_string, &error);

   if (!uri) {
      fprintf(stderr,
              "failed to parse URI:\n"
              "error message: %s\n",
              error.message);
      return EXIT_FAILURE;
   }

   client = mongoc_client_new_from_uri(uri);
   if (!client) {
      return EXIT_FAILURE;
   }

   coll = mongoc_client_get_collection(client, "db", "example_coll");

   mongoc_client_set_error_api(client, 2);
   /* insert a document */
   if (!mongoc_collection_insert_one(coll, to_insert, NULL, NULL, &error)) {
      fprintf(stderr, "insert failed: %s\n", error.message);
      return EXIT_FAILURE;
   }

   if (!mongoc_collection_update_one(coll, selector, update, NULL, NULL, &error)) {
      fprintf(stderr, "update failed: %s\n", error.message);
      return EXIT_FAILURE;
   }

   to_str = bson_as_relaxed_extended_json(to_insert, NULL);
   printf("inserted: %s\n", to_str);
   bson_free(to_str);

   cursor = mongoc_collection_find_with_opts(coll, selector, NULL, NULL);
   BSON_ASSERT(mongoc_cursor_next(cursor, &next_doc));
   printf("after update, collection has the following document:\n");

   to_str = bson_as_relaxed_extended_json(next_doc, NULL);
   printf("%s\n", to_str);
   bson_free(to_str);

   BSON_ASSERT(mongoc_collection_drop(coll, NULL));

   bson_destroy(to_insert);
   bson_destroy(update);
   bson_destroy(selector);
   mongoc_collection_destroy(coll);
   mongoc_uri_destroy(uri);
   mongoc_client_destroy(client);
   mongoc_cleanup();
   return EXIT_SUCCESS;
}

---

🎀 SEE ALSO 🎀

• MongoDB update command documentation, for more information on the update options 📚
• mongoc_collection_update_many() 💜
• mongoc_collection_replace_one() ⭐

---

🧚 AUTHOR 🧚

MongoDB, Inc 🫶

💅 COPYRIGHT 💅

2009-present, MongoDB, Inc.

---

and that's the whole page, bestie! this masterpiece is from version 2.5.6, dated Oct 09, 2026 — go forth and update exactly one document, you icon 👑💖