Docs Menu

Docs HomeMongoDB Manual


On this page

  • Definition
  • Behavior
  • Examples
db.collection.countDocuments(query, options)


mongosh Method

This page documents a mongosh method. This is not the documentation for database commands or language-specific drivers, such as Node.js.

For the database command, see the $group aggregation stage and the $sum expression called by the aggregate command.

For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.

For the legacy mongo shell documentation, refer to the documentation for the corresponding MongoDB Server release:

Returns the count of documents that match the query for a collection or view. This method is available for use in Transactions.

db.collection.countDocuments( <query>, <options> )
The query selection criteria. To count all documents, specify an empty document. See also Query Restrictions.
Optional. Extra options that affects the count behavior.

The options document can contain the following:

Optional. The maximum number of documents to count.
Optional. The number of documents to skip before counting.
string or document
Optional. An index name or the index specification to use for the query.
Optional. The maximum amount of time to allow the count to run.

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:

{ $match: <query> },
{ $group: { _id: null, n: { $sum: 1 } } }

Starting in version 4.2.1, 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.

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

Restricted Operator
As an alternative, use $expr instead.

As an alternative, use $geoWithin with $center; i.e.

{ $geoWithin: { $center: [ [ <x>, <y> ], <radius> ] } }

As an alternative, use $geoWithin with $centerSphere; i.e.

{ $geoWithin: { $centerSphere: [ [ <x>, <y> ], <radius> ] } }

db.collection.countDocuments() can be used inside multi-document transactions.

When you use db.collection.countDocuments() in a transaction, the resulting count will not filter out any uncommitted multi-document transactions.


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.

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

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


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


←  db.collection.count()db.collection.createIndex() →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.