MONGOC_COLLECT...DOCUMENT_COUNT(3)

okay so this is libmongoc's page for MONGOC_COLLECT...DOCUMENT_COUNT(3), and we're gonna get you comfy with it 💖 bestie, it's all about mongoc_collection_estimated_document_count() and yes, the “estimated” part is doing real work here.

💅 SYNOPSIS 💅

int64_t
mongoc_collection_estimated_document_count (mongoc_collection_t *collection,
                                            const bson_t *opts,
                                            const mongoc_read_prefs_t *read_prefs,
                                            bson_t *reply,
                                            bson_error_t *error);

🎀 PARAMETERS 🎀

• collection — a mongoc_collection_t. the main character we're counting stuff in 💅
• opts — a bson_t, or NULL if you wanna ignore it.
• read_prefs — a mongoc_read_prefs_t or NULL.
• reply — a maybe-NULL pointer to overwritable storage for a bson_t where the results go.
• error — an optional spot for a bson_error_t, or NULL.

opts can be NULL, or a BSON document with extra command options:

• readConcern — build a mongoc_read_concern_t and use mongoc_read_concern_append() to add the read concern to opts. there's example code for mongoc_client_read_command_with_opts(). read concern needs MongoDB 3.2 or newer, otherwise you get an error.
• sessionId — first make a mongoc_client_session_t with mongoc_client_start_session(). you can start a transaction with mongoc_client_session_start_transaction(), optionally with a mongoc_transaction_opt_t that overrides the options inherited from collection, then use mongoc_client_session_append() to add the session to opts. example code lives with mongoc_client_session_t.
• collation — sets up textual comparisons. check out Setting Collation Order and the MongoDB Manual entry on Collation. collation needs MongoDB 3.2 or newer, otherwise: error time 😭
• serverId — wanna target one specific server? include an int32 "serverId" field. get that id by calling mongoc_client_select_server(), then mongoc_server_description_id() on what it returns.
• skip — an int saying how many documents matching the query should be skipped before counting.
• limit — an int capping the max number of documents to count.
• comment — a bson_value_t specifying the comment to attach to this command. the comment will appear in log messages, profiler output, and currentOp output. requires MongoDB 4.4 or later.

want the full menu? see the MongoDB Manual entry on the count command. iykyk ✨

💅 DESCRIPTION 💅

this function runs a count query on collection. in contrast with mongoc_collection_count_documents(), the count it gives you is not guaranteed to be accurate. so like… it's giving estimate, not gospel 🔥

this one is 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.

✨ Behavior ✨

this method is implemented using the count command.

ok important lore: due to an oversight in versions 5.0.0-5.0.8 of MongoDB, the count command was not included in version "1" of the Stable API. applications using this method with the Stable API are recommended to upgrade their server version to 5.0.9+ or disable strict mode (via mongoc_server_api_strict()) to avoid encountering errors. no cap, read that twice if you need to 🫶

😭 ERRORS 😭

errors are propagated via the error parameter.

🫶 RETURNS 🫶

-1 on failure, otherwise the number of documents counted. slay ⭐

🌈 EXAMPLE 🌈

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

static void
print_count (mongoc_collection_t *collection, bson_t *query)
{
   bson_error_t error;
   int64_t count;
   bson_t* opts = BCON_NEW ("skip", BCON_INT64(5));

   count = mongoc_collection_estimated_document_count (
      collection, opts, NULL, NULL, &error);
   bson_destroy (opts);

   if (count < 0) {
      fprintf (stderr, "Count failed: %s\n", error.message);
   } else {
      printf ("%" PRId64 " documents counted.\n", count);
   }
}

👑 SEE ALSO 👑

• mongoc_collection_count_documents()
• Count: Behavior in the MongoDB Manual

🦋 AUTHOR 🦋

MongoDB, Inc

🍓 COPYRIGHT 🍓

2009-present, MongoDB, Inc.

---

okay that's the whole page, bestie — it's libmongoc version 2.5.6, dated Oct 09, 2024. mwah 💋✨