SYNOPSIS

int64_t
mongoc_collection_count_documents (mongoc_collection_t *collection,


                                   const bson_t *filter,


                                   const bson_t *opts,


                                   const mongoc_read_prefs_t *read_prefs,


                                   bson_t *reply,


                                   bson_error_t *error);

PARAMETERS

collection: A mongoc_collection_t.
filter: A bson_t containing the filter.
opts: A bson_t, NULL to ignore.
read_prefs: A mongoc_read_prefs_t or NULL.
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.

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

readConcern: Construct a mongoc_read_concern_t and use mongoc_read_concern_append() to add the read concern to opts. See the example code for mongoc_client_read_command_with_opts(). Read concern requires MongoDB 3.2 or later, otherwise an error is returned.
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.
skip: An int specifying how many documents matching the query should be skipped before counting.
limit: An int specifying the maximum 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. Only string values are supported prior to MongoDB 4.4.
hint: A document or string that specifies the index to use to support the query predicate.

Other options are included in the sent aggregate command. For a list of all options, see the MongoDB Manual entry on the aggregate command.

DESCRIPTION

This functions executes a count query on collection. In contrast with mongoc_collection_estimated_document_count(), the count returned is guaranteed to be accurate.

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.

ERRORS

Errors are propagated via the error parameter.

RETURNS

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

EXAMPLE

#include <bson/bson.h>
#include <mongoc/mongoc.h>
#include <stdio.h>
static void
print_count (mongoc_collection_t *collection, bson_t *filter)
{


   bson_error_t error;


   int64_t count;


   bson_t* opts = BCON_NEW ("skip", BCON_INT64(5));


   count = mongoc_collection_count_documents (


      collection, filter, 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);


   }
}

MIGRATING FROM DEPRECATED COUNT FUNCTIONS

When migrating to mongoc_collection_count_documents() from the deprecated mongoc_collection_count() or mongoc_collection_count_with_opts(), the following query operators in the filter must be replaced:

Operator	Replacement
$where	$expr
$near	$geoWithin with $center
$nearSphere	$geoWithin with $centerSphere

$expr requires MongoDB 3.6+

SEE ALSO:

mongoc_collection_estimated_document_count()

AUTHOR

MongoDB, Inc

COPYRIGHT

2009-present, MongoDB, Inc.