Count Documents

On this page

Overview

Sample Data
Retrieve an Accurate Count
Count All Documents
Count Specific Documents
Customize Count Behavior
Retrieve an Estimated Count
Customize Estimated Count Behavior
API Documentation

Overview

In this guide, you can learn how to retrieve accurate and estimated counts of the number of documents in a collection.

Sample Data

The examples in this guide use the movies collection in the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the Get Started with Atlas guide.

Retrieve an Accurate Count

Use the mongoc_collection_count_documents() function to count the number of documents that are in a collection. To count the number of documents that match specified search critera, pass a query filter to the mongoc_collection_count_documents() function.

To learn more about specifying a query, see Specify a Query.

Count All Documents

To return a count of all documents in the collection, call the mongoc_collection_count_documents() function with an empty query filter, as shown in the following example:

bson_error_t error;
bson_t *empty_query = bson_new ();
int64_t count = 
    mongoc_collection_count_documents (collection, empty_query, NULL, NULL, NULL, &error);
printf ("%" PRId64 "\n", count);
bson_destroy (empty_query);

Count Specific Documents

To return a count of documents that match specific search criteria, specify your query in the mongoc_collection_count_documents() function. The following example prints a count of all documents in the movies collection that have a year field value equal to 1930:

bson_error_t error;
bson_t *query = BCON_NEW ("year", BCON_INT32 (1930));
int64_t count =
    mongoc_collection_count_documents (collection, query, NULL, NULL, NULL, &error);
printf ("%" PRId64 "\n", count);
bson_destroy (query);

Customize Count Behavior

The mongoc_collection_count_documents() function accepts optional parameters in the form of a bson_t structure, which represents a set of options you can use to configure the count operation. If you don't specify any options, the driver does not customize the count operation.

The following table describes the options you can set to customize countDocuments():

Option	Description
`comment`	Specifies a comment to attach to the operation.
`skip`	Sets the number of documents to skip before returning results.
`limit`	Sets the maximum number of documents to count. Must be a positive integer.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.
`hint`	Sets the index to scan for documents.

For a complete list of options, see the API Documentation for mongoc_collection_count_documents().

The following example uses a bson_t structure to add a comment to the mongoc_collection_count_documents() operation:

bson_error_t error;
bson_t *opts = BCON_NEW ("comment", BCON_UTF8 ("Retrieving count"));
int64_t count =
    mongoc_collection_count_documents (collection, bson_new (), opts, NULL, NULL, &error);
printf ("%" PRId64 "\n", count);
bson_destroy (opts);

Retrieve an Estimated Count

Use the mongoc_collection_estimated_document_count() function to retrieve an estimate of the number of documents in a collection. The function estimates the amount of documents based on collection metadata, which can be faster than performing an accurate count.

The following example prints the estimated number of documents in a collection:

bson_error_t error;
int64_t count =
    mongoc_collection_estimated_document_count (collection, NULL, NULL, NULL, &error);
printf ("%" PRId64 "\n", count);

Customize Estimated Count Behavior

The mongoc_collection_estimated_document_count() function accepts optional parameters in the form of an bson_t structure, which represents options you can use to configure the count operation. If you don't specify any options, the driver does not customize the count operation.

The following table describes the options you can set to customize mongoc_collection_estimated_document_count():

Option	Description
`comment`	Specifies a comment to attach to the operation.
`collation`	Specifies the kind of language collation to use when sorting results. For more information, see Collation in the MongoDB Server manual.

For a complete list of options, see the API Documentation for mongoc_collection_estimated_document_count().

The following example uses a bson_t structure to add a comment to the mongoc_collection_estimated_document_count() operation:

bson_error_t error;
bson_t *opts = BCON_NEW ("comment", BCON_UTF8 ("Retrieving count"));
int64_t count =
    mongoc_collection_estimated_document_count (collection, opts, NULL, NULL, &error);
printf ("%" PRId64 "\n", count);
bson_destroy (opts);

API Documentation

To learn more about any of the functions discussed in this guide, see the following API documentation:

Back

Specify Documents to Return

Retrieve Distinct Field Values