Docs Menu
Docs Home
/
Languages
/
C++
/
C++ Driver
/
Read Data from MongoDB

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

Retrieve Distinct Field Values