MONGOC_COLLEC...MAND_WITH_OPTS(3)

💅 MONGOC_COLLECTION_WRITE_COMMAND_WITH_OPTS 💅

okay bestie, welcome to libmongoc — yes that's the manual we're living in today, and this page is all about mongoc_collection_write_command_with_opts. Buckle up, it's giving ✨specialised✨.

---

✨ SYNOPSIS ✨

bool
mongoc_collection_write_command_with_opts (mongoc_collection_t *collection,
                                           const bson_t *command,
                                           const bson_t *opts,
                                           bson_t *reply,
                                           bson_error_t *error);

---

🦋 DESCRIPTION 🦋

So what does this icon actually do? It executes a command on the server, but with extra logic baked in — logic that is specific to commands that write, and it takes the MongoDB server version into account. Like, it knows things. 💅

If you wanna send a raw command to the server with none of this logic (no thoughts, head empty), use mongoc_collection_command_simple() instead.

Use this function for commands that write, like "drop" or "createRole" — but not for "insert", "update", or "delete" (those have their own whole thing, see Basic Write Operations below, iykyk).

Write concern and collation can be overridden by various sources. ⚠️ Warning: in a transaction, read concern and write concern are prohibited in opts. Not optional, fr fr.

The highest-priority sources for these options are listed first. Here's the tea ☕:

Write Concern (highest priority first):

1. opts
2. Transaction
3. collection

Collation (highest priority first):

1. opts

And a lil detail that matters: the write concern is omitted for MongoDB before 3.4.

See the example for transactions and for the "distinct" command with opts.

Also super important: reply is always initialized, and must be freed with bson_destroy(). Don't forget, bestie, that's a leak waiting to happen 🫶

---

🌸 PARAMETERS 🌸

• _collection_ — A mongoc_collection_t.
• _command_ — A bson_t containing the command specification.
• _opts_ — A bson_t containing additional options.
• _reply_ — A maybe-NULL pointer to overwritable storage for a bson_t to contain the results.
• _error_ — An optional location for a bson_error_t or NULL.

---

🎀 the opts document, explained 🎀

opts may be NULL or a BSON document with additional command options:

• 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.
• 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. 💀
• serverId — To target a specific server, include an int32 "serverId" field. Obtain the id by calling mongoc_client_select_server(), then mongoc_server_description_id() on its return value.

Consult the MongoDB Manual entry on Database Commands for each command's arguments. 👑

---

😭 ERRORS 😭

Errors are propagated via the error parameter. That's the whole vibe. Simple, clean.

---

⭐ RETURNS ⭐

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

A write concern timeout or write concern error is considered a failure. 🙈 So don't go thinking a timeout is a cute little "maybe", it's a no.

---

🔥 BASIC WRITE OPERATIONS 🔥

Do not use this function to call the basic write commands "insert", "update", and "delete". Those commands require special logic not implemented in mongoc_collection_write_command_with_opts. Like, they're on a whole other level, this function is not invited to that party.

For basic write operations use CRUD functions such as mongoc_collection_insert_one() and the others described in the CRUD tutorial, or use the Bulk API. That's the slay route. 💖

---

🌈 EXAMPLE 🌈

See the example code for mongoc_client_read_command_with_opts().

---

👑 AUTHOR 👑

MongoDB, Inc

---

🧚 COPYRIGHT 🧚

2009-present, MongoDB, Inc.

---

and that's the whole page, bestie!! 💜✨ this little masterpiece came to you from libmongoc version 2.5.6, dated Oct 09, 2026 — mwah, go forth and write commands responsibly 🎀🦋💅