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 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