db.collection.countDocuments()¶

On this page

Definition
Behavior
Examples

Definition¶

db.collection.countDocuments(query, options)¶

mongo Shell Method

This page documents the mongo shell method, and does not refer to the MongoDB Node.js driver (or any other driver) method. For corresponding MongoDB driver API, refer to your specific MongoDB driver documentation instead.

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.

copy

db.collection.countDocuments( <query>, <options> )

Parameter	Type	Description
query	document	The query selection criteria. To count all documents, specify an empty document. See also Query Restrictions.
options	document	Optional. Extra options that affects the count behavior.

The options document can contain the following:

Field	Type	Description
`limit`	integer	Optional. The maximum number of documents to count.
`skip`	integer	Optional. The number of documents to skip before counting.
`hint`	string or document	Optional. An index name or the index specification to use for the query.
`maxTimeMS`	integer	Optional. The maximum amount of time to allow the count to run.

Behavior¶

Mechanics¶

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:

copy

db.collection.aggregate([
   { $match: <query> },
   { $group: { _id: null, n: { $sum: 1 } } }
])

Empty or Non-Existing Collections and Views¶

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¶

You cannot use the following query operators as part of the query expression for db.collection.countDocuments():

Restricted Operator	Alternative
`$where`	As an alternative, use `$expr` instead.
`$near`	As an alternative, use `$geoWithin` with `$center`; i.e. { $geoWithin: { $center: [ [ <x>, <y> ], <radius> ] } }
`$nearSphere`	As an alternative, use `$geoWithin` with `$centerSphere`; i.e. { $geoWithin: { $centerSphere: [ [ <x>, <y> ], <radius> ] } }

Transactions¶

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¶

Starting in MongoDB 4.2, if the client that issued the db.collection.countDocuments() disconnects before the operation completes, MongoDB marks the db.collection.countDocuments() for termination (i.e. killOp on the operation).

Examples¶

Count all Documents in a Collection¶

To count the number of all documents in the orders collection, use the following operation:

copy

db.orders.countDocuments({})

Count all Documents that Match a Query¶

Count the number of the documents in the orders collection with the field ord_dt greater than new Date('01/01/2012'):

copy

db.orders.countDocuments( { ord_dt: { $gt: new Date('01/01/2012') } }, { limit: 100 } )