MONGOC_CURSOR_..._COMMAND_REPLY(3)

💖 MONGOC_CURSOR_..._COMMAND_REPLY(3) — the libmongoc girlies know 💖

okay bestie, sit down, grab a boba, because we're talking about mongoc_cursor_new_from_command_reply() from libmongoc — yes that's the manual name, and yes it's a whole mouthful, iykyk 🫶

---

⚠️ WARNING ⚠️ (read this first fr fr)

Deprecated since version 1.11.0 😭 Use mongoc_cursor_new_from_command_reply_with_opts() instead. She's the upgraded version, the glow-up, the main character now.

When you migrate from the deprecated mongoc_cursor_new_from_command_reply() to mongoc_cursor_new_from_command_reply_with_opts(), keep this in mind bestie: options that you used to pass inside the reply argument (like "batchSize") have to go in the opts argument instead. Not optional, not a vibe, just how it is 💅

---

✨ SYNOPSIS ✨

mongoc_cursor_t *
mongoc_cursor_new_from_command_reply (mongoc_client_t *client,
                                      bson_t *reply,
                                      uint32_t server_id);

---

🎀 PARAMETERS 🎀

• client — a mongoc_client_t. Your client, your girl, your connection to everything 💜
• reply — the reply to a command, like "aggregate", "find", or "listCollections", that returns a cursor document. Heads up: the reply gets destroyed by mongoc_cursor_new_from_command_reply and you must not access it afterward. She's gone, she's not coming back, do not text her 🙈
• server_id — the opaque id of the server that was used to execute the command.

---

🌸 DESCRIPTION 🌸

So some MongoDB commands return a "cursor" document. Iconic behaviour honestly. Like, say you hit her with an "aggregate" command:

{ "aggregate" : "collection", "pipeline" : [], "cursor" : {}}

And the server replies like the queen she is:

{
   "cursor" : {
      "id" : 1234,
      "ns" : "db.collection",
      "firstBatch" : [ ]
   },
   "ok" : 1
}

mongoc_cursor_new_from_command_reply is a low-level function that initializes a mongoc_cursor_t from a reply exactly like that one. And extra options such as "tailable" or "awaitData" can be tucked right into the reply too — she contains multitudes ✨

Now, when you're synthesizing a completed cursor response that has no more batches (i.e. with cursor id 0), server_id may be 0. But if the cursor response is not completed (i.e. with a non-zero cursor id), you pass the server_id of the server used to create the cursor. Match the energy, match the id, no cap 🧚

Real talk though: use this function only if you're building a language driver that wraps the C Driver. If you're writing applications in C, higher-level functions like mongoc_collection_aggregate() are way more appropriate — and they keep you compatible with a range of MongoDB versions. It's giving "just use the nice one bestie" 🌈

---

👑 RETURNS 👑

A mongoc_cursor_t. If it fails, the cursor's error is set. Check for failure with mongoc_cursor_error() — always do the vibe check, never skip it 💀

---

💜 AUTHOR 💜

MongoDB, Inc

---

📜 COPYRIGHT 📜

2009-present, MongoDB, Inc.

---

and that's the whole page, bestie 🍓 you're officially educated, hydrated, and glowing. this was libmongoc version 1.30.13, dated Oct 09, 2024 — thank you for coming to my TED talk, periodt 💅✨🦋