MONGOC_COLLEC...IND_AND_MODIFY(3)

💅 MONGOC_COLLEC...IND_AND_MODIFY(3) ✨

okay so bestie, welcome to libmongoc — this is the page for mongoc_collection_find_and_modify(), and honestly? it's kind of a baddie. it does exactly what it says on the tin: finds a doc and modifies it. main character energy fr fr 🎀

---

🌸 SYNOPSIS

bool
mongoc_collection_find_and_modify (mongoc_collection_t *collection,
                                   const bson_t *query,
                                   const bson_t *sort,
                                   const bson_t *update,
                                   const bson_t *fields,
                                   bool _remove,
                                   bool upsert,
                                   bool _new,
                                   bson_t *reply,
                                   bson_error_t *error);

like, look at all those params. she's got a lot going on but we love her for it 💖

---

🎀 PARAMETERS

• collection — a mongoc_collection_t. your fave collection, the one you're working with.
• query — a bson_t holding the query that locates the target document(s). the "who are we talking about" energy.
• sort — a bson_t with the sort order for the query. lowkey important when multiple docs match.
• update — a bson_t with an update spec. the glow-up instructions ✨
• fields — an optional bson_t with the fields to return, or NULL. picky queen — only what you asked for.
• _remove — if the matching documents should be removed 👋
• upsert — if an upsert should be performed. i.e. "if it's not there, make it exist" 😌
• _new — if the new version of the document should be returned. spoiler: the new one is always better.
• 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. the "if things go wrong, put it here" slot.

---

🦋 DESCRIPTION

update and return an object. simple as that, periodt.

this is a thin wrapper around the findAndModify command. you need either update or _remove in there — one of them is literally required, no cap 🙅‍♀️

as of MongoDB 3.2, whatever mongoc_write_concern_t you spec'd on the mongoc_collection_t gets used, if any. so it's not ignored anymore, she's listening 💅

heads up bestie: reply is always initialized, and it must be freed with bson_destroy(). don't leave her hanging or you'll be leaking like 😭

on success, the output reply contains the full server reply to the findAndModify command. for what that reply is supposed to look like, check the MongoDB Manual page for findAndModify — that's where the deets live 🫶

---

🔥 ERRORS

errors are propagated via the error parameter. straightforward. no weird side quests.

---

👑 RETURNS

if you give it invalid arguments, or a server/network error happens — it returns false and sets error. nope, not today 🙈

otherwise? it succeeds and returns true. slay ⭐

⚠️ important vibe check: a write concern timeout or a write concern error counts as a failure. don't let that sneak past you.

SEE ALSO: mongoc_collection_find_and_modify_with_opts() — the fancy alternative, iykyk.

---

🌈 EXAMPLE

the file is find-and-modify.c, and here it is in all its glory:

#include <mongoc/mongoc.h>

#include <stdio.h>

int
main(void)
{
   mongoc_collection_t *collection;
   mongoc_client_t *client;
   const char *uri_string = "mongodb://127.0.0.1:27017/?appname=find-and-modify-example";
   mongoc_uri_t *uri;
   bson_error_t error;
   bson_t *query;
   bson_t *update;
   bson_t reply;
   char *str;

   mongoc_init();

   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;
   }

   mongoc_client_set_error_api(client, 2);
   collection = mongoc_client_get_collection(client, "test", "test");

   /*
    * Build our query, {"cmpxchg": 1}
    */
   query = BCON_NEW("cmpxchg", BCON_INT32(1));

   /*
    * Build our update. {"$set": {"cmpxchg": 2}}
    */
   update = BCON_NEW("$set", "{", "cmpxchg", BCON_INT32(2), "}");

   /*
    * Submit the findAndModify.
    */
   if (!mongoc_collection_find_and_modify(collection, query, NULL, update, NULL, false, false, true, &reply, &error)) {
      fprintf(stderr, "find_and_modify() failure: %s\n", error.message);
      return EXIT_FAILURE;
   }

   /*
    * Print the result as JSON.
    */
   str = bson_as_canonical_extended_json(&reply, NULL);
   printf("%s\n", str);
   bson_free(str);

   /*
    * Cleanup.
    */
   bson_destroy(query);
   bson_destroy(update);
   bson_destroy(&reply);
   mongoc_collection_destroy(collection);
   mongoc_uri_destroy(uri);
   mongoc_client_destroy(client);

   mongoc_cleanup();

   return EXIT_SUCCESS;
}

like, it builds a query {"cmpxchg": 1}, updates it with {"$set": {"cmpxchg": 2}}, calls the function, prints the reply as JSON, and cleans up after itself. a whole routine. iconic behavior honestly 🧚

---

💜 AUTHOR

MongoDB, Inc

🍓 COPYRIGHT

2009-present, MongoDB, Inc.

---

that's the whole page bestie!! this one's from libmongoc version 2.5.6, dated Oct 09, 2026, brought to you by the lovely humans at MongoDB, Inc. go forth and modify some documents responsibly 💖✨🎀