MONGOC_COLLECTION_FIND(3)

💅 MONGOC_COLLECTION_FIND — the libmongoc manual page, bestie edition

okay so you found mongoc_collection_find from libmongoc (that's section 3 of the manual, the C driver one, not the shell one — iykyk). buckle up, this one comes with a big fat deprecation warning at the top, so let's vibe-check that first. 🫶

⚠️ WARNING: Deprecated since version 1.5.0 — use mongoc_collection_find_with_opts() instead. bestie. she's a legacy icon but she is legacy. 💀

---

✨ SYNOPSIS ✨

mongoc_cursor_t *
mongoc_collection_find (mongoc_collection_t *collection,
                        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);

---

🎀 PARAMETERS 🎀

the way she takes eight arguments. high maintenance, but slay.

• collection: a mongoc_collection_t. the collection in question, obviously. 👑
• flags: a mongoc_query_flags_t. query flags, as one does.
• skip: a uint32_t of number of documents to skip, or 0.
• limit: a uint32_t of max number of documents to return, or 0.
• batch_size: a uint32_t containing batch size of document result sets, or 0 for default. and the default is 100. not me memorizing that. 🍓
• query: a bson_t containing the query and options to execute.
• fields: a bson_t containing fields to return, or NULL.
• read_prefs: a mongoc_read_prefs_t, or NULL for default read preferences.

---

🌸 DESCRIPTION 🌸

this function shall execute a query on the underlying collection. periodt.

if no options are necessary, query can simply contain a query such as {a:1}. but if you would like to specify options such as a sort order, the query must be placed inside of {"$query": {}}. there's an example below showing how to properly specify additional options to query, so don't freestyle it, fr fr.

the retryable read glow-up: this function is considered a retryable read operation. upon a transient error (a network error, errors due to replica set failover, etc.) the operation is safely retried once. if retryreads is false in the URI (see mongoc_uri_t) the retry behavior does not apply. no retry for you, bestie. 🙈

---

💖 RETURNS 💖

this function returns a newly allocated mongoc_cursor_t that should be freed with mongoc_cursor_destroy() when no longer in use. the returned mongoc_cursor_t is never NULL, even on error. and — this is the part everyone forgets — the user must call mongoc_cursor_next() on the returned mongoc_cursor_t to execute the initial command. it's giving lazy evaluation, it's giving main character energy.

cursor errors can be checked with mongoc_cursor_error_document(). it always fills out the bson_error_t if an error occurred, and optionally includes a server reply document if the error occurred server-side. so thorough. 💅

⚠️ WARNING: failure to handle the result of this function is a programming error. not a vibe. handle your return values, bestie, I am begging. 😭

---

⭐ EXAMPLE ⭐

Print All Documents in a Collection

#include <bson/bson.h>
#include <mongoc/mongoc.h>
#include <stdio.h>

static void
print_all_documents (mongoc_collection_t *collection)
{
   mongoc_cursor_t *cursor;
   bson_error_t error;
   const bson_t *doc;
   char *str;
   bson_t *query;

   query = BCON_NEW ("$query",
                     "{",
                     "foo",
                     BCON_INT32 (1),
                     "}",
                     "$orderby",
                     "{",
                     "bar",
                     BCON_INT32 (-1),
                     "}");
   cursor = mongoc_collection_find (
      collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

   while (mongoc_cursor_next (cursor, &doc)) {
      str = bson_as_canonical_extended_json (doc, NULL);
      printf ("%s\n", str);
      bson_free (str);
   }

   if (mongoc_cursor_error (cursor, &error)) {
      fprintf (stderr, "An error occurred: %s\n", error.message);
   }

   mongoc_cursor_destroy (cursor);
   bson_destroy (query);
}

notice how she frees str and destroys the cursor and destroys the query. that's called having your life together. 🌈

---

🦋 THE FIND COMMAND 🦋

queries have historically been sent as OP_QUERY wire protocol messages, but beginning in MongoDB 3.2 queries use the "find" command instead. glow up.

the driver automatically converts queries to the new "find" command syntax if needed, so this change is typically invisible to C Driver users. (iconic behavior, honestly.) however, an application written exclusively for MongoDB 3.2 and later can choose to use the new syntax directly instead of relying on the driver to convert from the old syntax:

/* MongoDB 3.2+ "find" command syntax */
query = BCON_NEW ("filter",
                  "{",
                  "foo",
                  BCON_INT32 (1),
                  "}",
                  "sort",
                  "{",
                  "bar",
                  BCON_INT32 (-1),
                  "}");
cursor = mongoc_collection_find (
   collection, MONGOC_QUERY_NONE, 0, 0, 0, query, NULL, NULL);

the "find" command takes different options from the traditional OP_QUERY message. here's the translation chart, but make it a list because we're not doing tables here:

• Query — $query — filter
• Sort — $orderby — sort
• Show record location — $showDiskLoc — showRecordId
• Other $-options — $<option name> — <option name>

most applications should use the OP_QUERY syntax, with "$query", "$orderby", and so on, and rely on the driver to convert to the new syntax if needed. lowkey the move.

SEE ALSO: the "find" command in the MongoDB Manual.

---

🔥 THE EXPLAIN COMMAND 🔥

with MongoDB before 3.2, a query with option $explain: true returns information about the query plan, instead of the query results. beginning in MongoDB 3.2, there is a separate "explain" command. and listen — the driver will not convert "$explain" queries to "explain" commands. you must call the "explain" command explicitly:

/* MongoDB 3.2+, "explain" command syntax */
command = BCON_NEW ("explain",
                    "{",
                    "find",
                    BCON_UTF8 ("collection_name"),
                    "filter",
                    "{",
                    "foo",
                    BCON_INT32 (1),
                    "}",
                    "}");
mongoc_collection_command_simple (collection, command, NULL, &reply, &error);

SEE ALSO: the "explain" command in the MongoDB Manual.

---

👑 AUTHOR 👑

MongoDB, Inc

💜 COPYRIGHT 💜

2009-present, MongoDB, Inc.

---

and that's the whole page, bestie. she's from libmongoc version 1.30.13, dated Oct 09, 2026, and she's the section 3 manual page MONGOC_COLLECTION_FIND. deprecated but never forgotten. 🕊️✨ go call mongoc_collection_find_with_opts() instead tho, I'm serious. 💖