/ /

Count Documents

Overview

In this guide, you can learn how to use the C++ driver to retrieve an accurate and estimated count of the number of documents in a collection. The count_documents() method returns the exact number of documents that match a query filter or that exist in a collection, and the estimated_document_count() method returns the estimated number of documents in a collection.

Sample Data

The examples in this guide use the companies collection in the sample_training database from the Atlas sample datasets. To access this collection from your C++ application, instantiate a mongocxx::client that connects to an Atlas cluster and assign the following values to your db and collection variables:

auto db = client["sample_training"];
auto collection = db["companies"];

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 count_documents() method to count the number of documents that are in a collection. To count the number of documents that match a specific search critera, pass a query filter document to the count_documents() method.

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

Count All Documents

To return a count of all documents in the collection, pass an empty filter document to the count_documents() method, as shown in the following example:

auto result = collection.count_documents({});
std::cout << "Number of documents: " << result << std::endl;

Number of documents: 9500

Count Specific Documents

To return a count of documents that match specific search criteria, pass your query filter document to the count_documents() method.

The following example counts the number of documents that have a founded_year value of 2010:

auto result = collection.count_documents(make_document(kvp("founded_year", 2010)));
std::cout << "Number of companies founded in 2010: " << result << std::endl;

Number of companies founded in 2010: 33

Customize Count Behavior

You can modify the behavior of the count_documents() method by passing an instance of the mongocxx::options::count class as a parameter. The following table describes the fields you can set in a mongocxx::options::count instance:

Field	Description
`collation`	The collation to use for the operation. Type: `bsoncxx::document::view_or_value`
`hint`	The index to use for the operation. Type: `mongocxx::hint`
`comment`	The comment to attach to the operation. Type: `bsoncxx::types::bson_value::view_or_value`
`limit`	The maximum number of documents to count. This value must be a positive integer. Type: `std::int64_t`
`max_time`	The maximum amount of time in milliseconds that the operation can run. Type: `std::chrono::milliseconds`
`skip`	The number of documents to skip before counting documents. Type: `std::int64_t`
`read_preference`	The read preference to use for the operation. Type: `mongocxx::read_preference`

The following example uses the count_documents() method to count the number of documents in which the number_of_employees field has the value 50 and instructs the operation to count a maximum of 100 results:

mongocxx::options::count opts;
opts.limit(100); 
auto result = collection.count_documents(make_document(kvp("number_of_employees", 50)), opts);
std::cout << "Number of companies with 50 employees: " << result << std::endl;

Number of companies with 50 employees: 100

Retrieve an Estimated Count

You can retrieve an estimate of the number of documents in a collection by calling the estimated_document_count() method. The method estimates the amount of documents based on collection metadata, which might be faster than performing an accurate count.

The following example estimates the number of documents in a collection:

auto result = collection.estimated_document_count();
std::cout << "Estimated number of documents: " << result << std::endl;

Estimated number of documents: 9500

Customize Estimated Count Behavior

You can modify the behavior of the estimated_document_count() method by passing an instance of the mongocxx::options::estimated_document_count class as a parameter. The following table describes the fields you can set in a mongocxx::options::estimated_document_count instance:

Field	Description
`max_time`	The maximum amount of time in milliseconds that the operation can run. Type: `std::chrono::milliseconds`
`comment`	The comment to attach to the operation. Type: `bsoncxx::types::bson_value::view_or_value`
`read_preference`	The read preference to use for the operation. Type: `mongocxx::read_preference`

The following example uses the estimated_document_count() method to return an estimate of the number of documents in the collection and instructs the operation to run for a maximum of 1000 milliseconds:

mongocxx::options::estimated_document_count opts;
opts.max_time(std::chrono::milliseconds{1000}); 
auto result = collection.estimated_document_count(opts);
std::cout << "Estimated number of documents: " << result << std::endl;

Estimated number of documents: 9500

API Documentation

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

Back

Distinct Field Values

Cursors