cursor.count()

Definition

  • cursor.count()

mongo Shell Method

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

Note

MongoDB drivers compatible with the 4.0 features deprecate theirrespective cursor and collection count() APIs in favor of newAPIs that corresponds to countDocuments() andestimatedDocumentCount(). For the specific API names for agiven driver, see the driver API documentation.

Counts the number of documents referenced by a cursor. Append thecount() method to afind() query to return the number ofmatching documents. The operation does not perform the query butinstead counts the results that would be returned by the query.

Important

  • Avoid using count() if thefind() operation is run without aquery predicate since without the query predicate, thesecount() returns results based on thecollection’s metadata, which may result in an approximatecount. In particular,
    • On a sharded cluster, the resulting count will not correctlyfilter out orphaned documents.
    • After an unclean shutdown, the count may beincorrect.
  • For counts based on collection metadata, see alsocollStats pipeline stage with the countoption.

The count() method has the followingprototype form:

  1. db.collection.find(<query>).count()

The count() method has the followingparameter:

ParameterTypeDescriptionapplySkipLimitbooleanOptional. Specifies whether to consider the effects of thecursor.skip() and cursor.limit() methods in thecount. By default, the count() methodignores the effects of the cursor.skip() andcursor.limit(). Set applySkipLimit to true toconsider the effect of these methods.

MongoDB also provides an equivalent db.collection.count()as an alternative to the db.collection.find(<query>).count()construct.

MongoDB supports the use of hint() withcount(). See Specify the Index to Use for anexample.

See also

cursor.size()

Behavior

Count and Transactions

You cannot use count and shell helperscount() and db.collection.count() intransactions.

For details, see Transactions and Count Operations.

Sharded Clusters

On a sharded cluster, count() without a query predicate in the find can result in an inaccurate count iforphaned documents exist or if achunk migration is in progress.

To avoid these situations, on a sharded cluster, use thedb.collection.aggregate() method:

You can use the $count stage to count the documents. Forexample, the following operation counts the documents in a collection:

  1. db.collection.aggregate( [
  2.    { $count: "myCount" }
  3. ])

The $count stage is equivalent to the following$group + $project sequence:

  1. db.collection.aggregate( [
  2.    { $group: { _id: null, count: { $sum: 1 } } }
  3.    { $project: { _id: 0 } }
  4. ] )

See also

$collStats to return an approximate count based on the collection’s metadata.

Index Use

Consider a collection with the following index:

  1. { a: 1, b: 1 }

When performing a count, MongoDB can return the count using only theindex if:

  • the query can use an index,
  • the query only contains conditions on the keys of the index, and
  • the query predicates access a single contiguous range of index keys.

For example, the following operations can return the count using onlythe index:

  1. db.collection.find( { a: 5, b: 5 } ).count()
  2. db.collection.find( { a: { $gt: 5 } } ).count()
  3. db.collection.find( { a: 5, b: { $gt: 10 } } ).count()

If, however, the query can use an index but the query predicates do notaccess a single contiguous range of index keys or the query alsocontains conditions on fields outside the index, then in addition tousing the index, MongoDB must also read the documents to return thecount.

  1. db.collection.find( { a: 5, b: { $in: [ 1, 2, 3 ] } } ).count()
  2. db.collection.find( { a: { $gt: 5 }, b: 5 } ).count()
  3. db.collection.find( { a: 5, b: 5, c: 5 } ).count()

In such cases, during the initial read of the documents, MongoDB pagesthe documents into memory such that subsequent calls of the same countoperation will have better performance.

Examples

The following are examples of the count() method.

Count All Documents

The following operation counts the number of all documents in theorders collection:

  1. db.orders.find().count()

Count Documents That Match a Query

The following operation counts the number of the documents in theorders collection with the field ord_dt greater than newDate('01/01/2012'):

  1. db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).count()

Limit Documents in Count

The following operation counts the number of the documents in theorders collection with the field orddt greater than newDate('01/01/2012') _taking into account the effect of thelimit(5):

  1. db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).limit(5).count(true)

Specify the Index to Use

The following operation uses the index named "status_1", which hasthe index key specification of { status: 1 }, to return a count ofthe documents in the orders collection with the field ord_dtgreater than new Date('01/01/2012') and the status field isequal to "D":

  1. db.orders.find(
  2.    { ord_dt: { $gt: new Date('01/01/2012') }, status: "D" }
  3. ).hint( "status_1" ).count()