count
On this page
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 thecount()
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 thecount
command) in favor of new APIs that corresponds tocountDocuments()
andestimatedDocumentCount()
. 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:FieldTypeDescriptioncount
stringThe name of the collection or view to count.query
documentOptional. A query that selects which documents to count in the collection or view.limit
integerOptional. The maximum number of matching documents to return.skip
integerOptional. The number of matching documents to skip before returning results.hint
string or documentOptional. The index to use. Specify either the index name as a string or the index specification document.readConcern
documentOptional. 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 theprimary
only.
For more formation on the read concern levels, see Read Concern Levels.
maxTimeMS
non-negative integerOptional.
Specifies a time limit in milliseconds. If you do not specify a value for
maxTimeMS
, operations will not time out. A value of0
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
documentOptional.
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
anyOptional. 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 thecommand.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 } } ] )
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 thecollStats
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 nonemptyquery
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.