Count Documents
On this page
Overview
In this guide, you can learn how to use the Ruby driver to retrieve an accurate and estimated count of the number of documents in a collection. The following methods count documents in a collection:
count_documents: Returns the exact number of documents that match a query filter or that exist in a collectionestimated_document_count: Returns the estimated number of documents that exist 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 Ruby application, create a Mongo::Client object that connects to
an Atlas cluster and assign the following values to your database and collection
variables:
database = client.use('sample_training') collection = database['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
in a collection. To count the number of documents that match specific search criteria,
pass a query filter to the count_documents method.
Count All Documents
To return a count of all documents in the collection, call the
count_documents method without passing a query filter, as shown
in the following example:
result = collection.count_documents puts "Number of documents: #{result}"
Number of documents: 9500
Count Specific Documents
To return a count of documents that match specific search criteria, pass a query
filter to the count_documents method.
The following example counts the number of documents in which the value of the
founded_year field is 2010:
result = collection.count_documents(founded_year: 2010) puts "Number of companies founded in 2010: #{result}"
Number of companies founded in 2010: 33
Customize Count Behavior
You can modify the behavior of the count_documents method by
passing a second parameter that specifies option values. The following table
describes the options you can set to customize the count operation:
Option | Description |
|---|---|
| The collation to use for the operation. Type: Hash |
| The index to use for the operation. Type: Hash |
| The comment to attach to the operation. Type: Object |
| The maximum number of documents to count. This value must be a positive integer. Type: Integer |
| The maximum amount of time in milliseconds that the operation can run. Type: Integer |
| The number of documents to skip before counting documents. Type: Integer |
| The read preference to use for the operation. To learn more, see
Read Preference in the MongoDB Server manual. Type: Hash |
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:
result = collection.count_documents({ number_of_employees: 50 }, limit: 100) puts "Number of companies with 50 employees: #{result}"
Number of companies with 50 employees: 100
Important
When you pass an options parameter to the count_documents method,
you must enclose the query filter in brackets ({}).
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:
result = collection.estimated_document_count puts "Estimated number of documents: #{result}"
Estimated number of documents: 9500
Customize Estimated Count Behavior
You can modify the behavior of the estimated_document_count method
by passing a parameter that specifies option values. The
following table describes the options you can set to customize
the operation:
Option | Description |
|---|---|
| The comment to attach to the operation. Type: Object |
| The maximum amount of time in milliseconds that the operation can run. Type: Integer |
| The read concern to use for the operation. To learn more, see
Read Concern in the MongoDB Server manual. Type: Hash |
The following example uses the estimated_document_count method to return an
estimate of the number of documents in the collection and sets a timeout of
1000 milliseconds on the operation:
result = collection.estimated_document_count(max_time_ms: 1000) puts "Estimated number of documents: #{result}"
Estimated number of documents: 9500
API Documentation
To learn more about any of the methods discussed in this guide, see the following API documentation: