MONGOC_CLIENT_COMMAND(3)

💅 mongoc_client_command(3) — a libmongoc moment

okay bestie, gather round, because we're talking about mongoc_client_command from libmongoc, and there is some tea to spill right at the top. 🫖

⚠️ WARNING: Deprecated since version 1.29.0. This function is deprecated and should not be used in new code. Use mongoc_client_command_simple() instead. 🚫

like… she's iconic but she's retired, you know? moving on. 👑

---

✨ SYNOPSIS ✨

mongoc_cursor_t *
mongoc_client_command (mongoc_client_t *client,
                       const char *db_name,
                       mongoc_query_flags_t flags,
                       uint32_t skip,
                       uint32_t limit,
                       uint32_t batch_size,
                       const bson_t *query,
                       const bson_t *fields,
                       const mongoc_read_prefs_t *read_prefs);

and a lil PSA: this function is not considered a retryable read operation. no retries, no do-overs, it's giving one-shot. 💀

---

🦋 DESCRIPTION 🦋

so what does she actually do? she creates a cursor that will execute the command when you call mongoc_cursor_next() on it. lazy girl behavior, honestly, and we respect it. ✨

important vibe check though: the client's read preference, read concern, and write concern are not applied to the command. and mongoc_cursor_next() will not check the server response for a write concern error or write concern timeout. so don't come for her later, she told you upfront. 😭

if mongoc_cursor_next() returns false, then go retrieve your error details with mongoc_cursor_error() or mongoc_cursor_error_document(). that's where the lore lives. 🔍

---

🎀 PARAMETERS 🎀

• client — A mongoc_client_t. the main character. 👑
• db_name — The name of the database to run the command on.
• flags — Unused. literally just vibing there. 💤
• skip — Unused. also napping.
• limit — Unused. same energy.
• batch_size — Unused. not her moment.
• query — A bson_t containing the command specification. this one actually matters bestie. 🔥
• fields — Unused. decorative.
• read_prefs — An optional mongoc_read_prefs_t. otherwise, the command uses mode MONGOC_READ_PRIMARY. 🌸

---

🌈 MIGRATING 🌈

so mongoc_client_command() is deprecated. periodt. 💅

here's the glow-up, side by side. first, the old way:

Before

const bson_t *reply;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
mongoc_cursor_t *cursor = mongoc_client_command (client,
                                                 "db",
                                                 MONGOC_QUERY_NONE /* unused */,
                                                 0 /* unused */,
                                                 0 /* unused */,
                                                 0 /* unused */,
                                                 cmd,
                                                 NULL /* unused */,
                                                 NULL /* read prefs */);
// Expect cursor to return exactly one document for the command reply.
EXPECT (mongoc_cursor_next (cursor, &reply));

bson_error_t error;
if (mongoc_cursor_error (cursor, &error)) {
   FAIL ("Expected no error, got: %s\n", error.message);
}

// Expect successful reply to contain "ok": 1
bson_iter_t iter;
EXPECT (bson_iter_init_find (&iter, reply, "ok") && bson_iter_as_int64 (&iter) == 1);

// Expect cursor to return no other documents.
EXPECT (!mongoc_cursor_next (cursor, &reply));
mongoc_cursor_destroy (cursor);
bson_destroy (cmd);

The above code block may be rewritten to use mongoc_client_command_simple() instead, as shown below:

After

bson_t reply;
bson_error_t error;
bson_t *cmd = BCON_NEW ("find", "foo", "filter", "{", "}");
if (!mongoc_client_command_simple (client, "db", cmd, NULL /* read prefs */, &reply, &error)) {
   FAIL ("Expected no error, got: %s\n", error.message);
}

// Expect successful reply to contain "ok": 1
bson_iter_t iter;
EXPECT (bson_iter_init_find (&iter, reply, "ok") && bson_iter_as_int64 (&iter) == 1);

bson_destroy (&reply);
bson_destroy (cmd);

see? cursor-free, chaos-free, slay. 🧚✨

---

💖 RETURNS 💖

A mongoc_cursor_t. 💫

and listen: the cursor should be freed with mongoc_cursor_destroy(). don't leave her hanging, that's a memory leak and it's not cute. 🚮

---

⭐ AUTHOR ⭐

MongoDB, Inc

👑 COPYRIGHT 👑

2009-present, MongoDB, Inc.

---

and that's the whole page bestie — libmongoc, version 1.30.13, dated Oct 09, 2026, MONGOC_CLIENT_COMMAND(3). go forth and use mongoc_client_command_simple() instead, ily, mwah 💋