/ /

Database Commands

Aggregation Commands

Docs Home

MongoDB Manual

Reference

Database Commands

Aggregation Commands

count

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Definition

count

Counts the number of documents in a collection or a view. Returns a document that contains this count and as well as the command status.

Tip

In the mongo Shell, this command can also be run through the count() helper method.

Helper methods are convenient for mongo users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

Note

MongoDB drivers compatible with the 4.0 features deprecate their respective cursor and collection count() APIs (which runs the count command) in favor of new APIs that corresponds to countDocuments() and estimatedDocumentCount(). For the specific API names for a given driver, see the driver API documentation.

count has the following form:

Note

Starting in version 4.2, MongoDB implements a stricter validation of the option names for the count command. The command now errors if you specify an unknown option name.

{
  count: <collection or view>,
  query: <document>,
  limit: <integer>,
  skip: <integer>,
  hint: <hint>,
  readConcern: <document>,
  maxTimeMS: <integer>,
  collation: <document>,
  comment: <any>
}

count has the following fields:

Field

Type

Description

count

string

The name of the collection or view to count.

query

document

Optional. A query that selects which documents to count in the collection or view.

limit

integer

Optional. The maximum number of matching documents to return.

skip

integer

Optional. The number of matching documents to skip before returning results.

hint

string or document

Optional. The index to use. Specify either the index name as a string or the index specification document.

readConcern

document

Optional. Specifies the read concern. The option has the following syntax:

readConcern: { level: <value> }

Possible read concern levels are:

"local". This is the default read concern level for read operations against primary and read operations against secondaries when associated with causally consistent sessions.
"available". This is the default for reads against secondaries when when not associated with causally consistent sessions. The query returns the instance's most recent data.
"majority". Available for replica sets that use WiredTiger storage engine.
"linearizable". Available for read operations on the primary only.

For more formation on the read concern levels, see Read Concern Levels.

maxTimeMS

non-negative integer

Optional.

Specifies a time limit in milliseconds. If you do not specify a value for maxTimeMS, operations will not time out. A value of 0 explicitly specifies the default unbounded behavior.

MongoDB terminates operations that exceed their allotted time limit using the same mechanism as db.killOp(). MongoDB only terminates an operation at one of its designated interrupt points.

collation

document

Optional.

Specifies the collation to use for the operation.

Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks.

The collation option has the following syntax:

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.

If the collation is unspecified but the collection has a default collation (see db.createCollection()), the operation uses the collation specified for the collection.

If no collation is specified for the collection or for the operations, MongoDB uses the simple binary comparison used in prior versions for string comparisons.

You cannot specify multiple collations for an operation. For example, you cannot specify different collations per field, or if performing a find with a sort, you cannot use one collation for the find and another for the sort.

New in version 3.4.

comment

any

Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations:

mongod log messages, in the attr.command.cursor.comment field.
Database profiler output, in the command.comment field.
currentOp output, in the command.comment field.

A comment can be any valid BSON type (string, integer, object, array, etc).

New in version 4.4.

Note

Prior to v4.4.14, MongoDB only supports BSON type string. Starting in v4.4.14, a comment can be any valid BSON type.

Important

Avoid using the count and its wrapper methods without a query predicate (note: db.collection.estimatedDocumentCount() does not take a query predicate) since without the query predicate, these operations return results based on the collection's metadata, which may result in an approximate count. In particular,
- On a sharded cluster, the resulting count will not correctly filter out orphaned documents.
- After an unclean shutdown, the count may be incorrect.
For counts based on collection metadata, see also collStats pipeline stage with the count option.

Behavior

Count and Transactions

You cannot use count and shell helpers count() and db.collection.count() in transactions.

For details, see Transactions and Count Operations.

Accuracy and Sharded Clusters

On a sharded cluster, the count command when run without a query predicate can result in an inaccurate count if orphaned documents exist or if a chunk migration is in progress.

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

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

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

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

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

Tip

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

Accuracy after Unexpected Shutdown

After an unclean shutdown of a mongod using the Wired Tiger storage engine, count statistics reported by count may be inaccurate.

The amount of drift depends on the number of insert, update, or delete operations performed between the last checkpoint and the unclean shutdown. Checkpoints usually occur every 60 seconds. However, mongod instances running with non-default --syncdelay settings may have more or less frequent checkpoints.

Run validate on each collection on the mongod to restore statistics after an unclean shutdown.

After an unclean shutdown:

validate updates the count statistic in the collStats output with the latest value.
Other statistics like the number of documents inserted or removed in the collStats output are estimates.

Note

This loss of accuracy only applies to count operations that do not include a query document.

Client Disconnection

Starting in MongoDB 4.2, if the client that issued count disconnects before the operation completes, MongoDB marks count for termination using killOp.

Examples

The following sections provide examples of the count command.

Count All Documents

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

db.runCommand( { count: 'orders' } )

In the result, the n, which represents the count, is 26, and the command status ok is 1:

{ "n" : 26, "ok" : 1 }

Count Documents That Match a Query

The following operation returns a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012'):

db.runCommand( { count:'orders',
                 query: { ord_dt: { $gt: new Date('01/01/2012') } }
               } )

In the result, the n, which represents the count, is 13 and the command status ok is 1:

{ "n" : 13, "ok" : 1 }

Skip Documents in Count

The following operation returns a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012') and skip the first 10 matching documents:

db.runCommand( { count:'orders',
                 query: { ord_dt: { $gt: new Date('01/01/2012') } },
                 skip: 10 }  )

In the result, the n, which represents the count, is 3 and the command status ok is 1:

{ "n" : 3, "ok" : 1 }

Specify the Index to Use

The following operation uses the index { status: 1 } to return a count of the documents in the orders collection where the value of the ord_dt field is greater than Date('01/01/2012') and the status field is equal to "D":

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

In the result, the n, which represents the count, is 1 and the command status ok is 1:

{ "n" : 1, "ok" : 1 }

Override Default Read Concern

To override the default read concern level of "local", use the readConcern option.

The following operation on a replica set specifies a Read Concern of "majority" to read the most recent copy of the data confirmed as having been written to a majority of the nodes.

Important

To use read concern level of "majority", replica sets must use WiredTiger storage engine.
You can disable read concern "majority" for a deployment with a three-member primary-secondary-arbiter (PSA) architecture; however, this has implications for change streams (in MongoDB 4.0 and earlier only) and transactions on sharded clusters. For more information, see Disable Read Concern Majority.
To use the readConcern level of "majority", you must specify a nonempty query condition.
Regardless of the read concern level, the most recent data on a node may not reflect the most recent version of the data in the system.

db.runCommand(
   {
     count: "restaurants",
     query: { rating: { $gte: 4 } },
     readConcern: { level: "majority" }
   }
)

To ensure that a single thread can read its own writes, use "majority" read concern and "majority" write concern against the primary of the replica set.

Back

aggregate

distinct