Docs Home → Develop Applications → MongoDB Manual
db.collection.countDocuments()![](/docs/v5.2/assets/link.svg)
On this page
Definition![](/docs/v5.2/assets/link.svg)
db.collection.countDocuments(query, options)
Important
mongosh Method
This is a
mongosh
method. This is not the documentation forNode.js
or other programming language specific driver methods.In most cases,
mongosh
methods work the same way as the legacymongo
shell methods. However, some legacy methods are unavailable inmongosh
.For the legacy
mongo
shell documentation, refer to the documentation for the corresponding MongoDB Server release:For MongoDB API drivers, refer to the language specific MongoDB driver documentation.
New in version 4.0.3.
Returns the count of documents that match the query for a collection or view. The method wraps the
$group
aggregation stage with a$sum
expression to perform the count and is available for use in Transactions.db.collection.countDocuments( <query>, <options> ) ParameterTypeDescriptionquerydocumentThe query selection criteria. To count all documents, specify an empty document. See also Query Restrictions.optionsdocumentOptional. Extra options that affects the count behavior.The
options
document can contain the following:FieldTypeDescriptionlimit
integerOptional. The maximum number of documents to count.skip
integerOptional. The number of documents to skip before counting.hint
string or documentOptional. An index name or the index specification to use for the query.maxTimeMS
integerOptional. The maximum amount of time to allow the count to run.
Behavior![](/docs/v5.2/assets/link.svg)
Mechanics![](/docs/v5.2/assets/link.svg)
Unlike db.collection.count()
,
db.collection.countDocuments()
does not use the metadata to
return the count. Instead, it performs an aggregation of the document
to return an accurate count, even after an unclean shutdown or in the
presence of orphaned documents in a sharded
cluster.
db.collection.countDocuments()
wraps the following
aggregation operation and returns just the value of n
:
db.collection.aggregate([ { $match: <query> }, { $group: { _id: null, n: { $sum: 1 } } } ])
Empty or Non-Existing Collections and Views![](/docs/v5.2/assets/link.svg)
Starting in version 4.2.1 (and 4.0-series in 4.0.13),
db.collection.countDocuments()
returns 0
on an empty or
non-existing collection or view.
In earlier versions of MongoDB, db.collection.countDocuments()
errors on an empty or non-existing collection or view.
Query Restrictions![](/docs/v5.2/assets/link.svg)
You cannot use the following query operators as part of the query
expression for db.collection.countDocuments()
:
Restricted Operator | Alternative | |
---|---|---|
As an alternative, use $expr instead. | ||
As an alternative, use
| ||
As an alternative, use
|
Transactions![](/docs/v5.2/assets/link.svg)
db.collection.countDocuments()
can be used inside multi-document transactions.
Important
In most cases, multi-document transaction incurs a greater performance cost over single document writes, and the availability of multi-document transactions should not be a replacement for effective schema design. For many scenarios, the denormalized data model (embedded documents and arrays) will continue to be optimal for your data and use cases. That is, for many scenarios, modeling your data appropriately will minimize the need for multi-document transactions.
For additional transactions usage considerations (such as runtime limit and oplog size limit), see also Production Considerations.
Client Disconnection![](/docs/v5.2/assets/link.svg)
Starting in MongoDB 4.2, if the client that issued db.collection.countDocuments()
disconnects before the operation completes, MongoDB marks db.collection.countDocuments()
for termination using killOp
.
Examples![](/docs/v5.2/assets/link.svg)
Count all Documents in a Collection![](/docs/v5.2/assets/link.svg)
To count the number of all documents in the orders
collection, use
the following operation:
db.orders.countDocuments({})
Count all Documents that Match a Query![](/docs/v5.2/assets/link.svg)
Count the number of the documents in the orders
collection with the field ord_dt
greater than new
Date('01/01/2012')
:
db.orders.countDocuments( { ord_dt: { $gt: new Date('01/01/2012') } }, { limit: 100 } )