$collStats (aggregation)

Definition

  • $collStats

New in version 3.4.

Returns statistics regarding a collection or view.

The $collStats stage has the following prototype form:

  1. {
  2.   $collStats:
  3.     {
  4.       latencyStats: { histograms: <boolean> },
  5.       storageStats: { scale: <number> },
  6.       count: {}
  7.     }
  8. }

The $collStats stage accepts an argument document with thefollowing optional fields:

Field NameDescriptionlatencyStatsAdds latency statistics to thereturn document.latencyStats.histogramsAdds latency histogram information to the embedded documentsin latencyStats if true.storageStatsAdds storage statistics to thereturn document.

  • Specify an empty document (i.e. storageStats: {}) touse the default scale factor of 1 for the various sizedata. Scale factor of 1 displays the returned sizes inbytes.

  • Specify the scale factor (i.e. storageStats: { scale:<number> }) to use the specified scale factor for thevarious size data. For example, to display kilobytes ratherthan bytes, specify a scale value of 1024.

If you specify a non-integer scale factor, MongoDB uses the integerpart of the specified factor. For example, if you specify a scalefactor of 1023.999, MongoDB uses 1023 as the scale factor.

The scale factor does not affect those sizes that specifythe unit of measurement in the field name, such as "bytescurrently in the cache".countAdds the total number of documents in the collection to thereturn document.

Note

The count is based on the collection’s metadata, whichprovides a fast but sometimes inaccurate count for shardedclusters.

See count Field

New in version 3.6.

For a collection in a replica set or anon-sharded collection ina cluster, $collStats outputs a single document. For asharded collection,$collStats outputs one document per shard. The output documentincludes the following fields:

Field NameDescriptionnsThe namespace of the requested collection or view.shardThe name of the shard the output document corresponds to.

Only present when $collStats runs on a sharded cluster. Bothsharded and non-sharded collectionswill produce this field.

New in version 3.6.

hostThe hostname and port of the mongod process which producedthe output document.

New in version 3.6.

localTimeThe current time on the MongoDB server, expressed as UTCmilliseconds since the Unix epoch.latencyStatsA collection of statistics related to request latency for acollection or view. SeelatencyStats Document for details on this document.

Only present when the latencyStats: {} option is specified.storageStatsA collection of statistics related to a collection’s storageengine. See storageStats Document for details on thisdocument.

The various size data is scaled by the specified factor (withthe exception of those sizes that specify the unit ofmeasurement in the field name).

Only present when the storageStats option is specified.

Returns an error if applied to a view.countThe total number of documents in the collection. This data isalso available in storageStats.count.

Note

The count is based on the collection’s metadata, whichprovides a fast but sometimes inaccurate count for shardedclusters.

Only present when the count: {} option is specified. Returnsan error if applied to a view.

Behavior

$collStats must be the first stage in an aggregation pipeline, orelse the pipeline returns an error.

Transactions

$collStats is not allowed in transactions.

latencyStats Document

The latencyStats embedded document only exists in the output ifyou specify the latencyStats option.

Field NameDescription
readsLatency statistics for read requests.
writesLatency statistics for write requests.
commandsLatency statistics for database commands.

Each of these fields contains an embedded document bearing thefollowing fields:

Field NameDescription
latencyA 64-bit integer giving the total combinedlatency in microseconds.
opsA 64-bit integer giving the total number ofoperations performed on the collection since startup.
histogramAn array of embedded documents, each representing a latency range.Each document covers twice the previous document’s range. Forupper values between 2048 microseconds and roughly 1 second,the histogram includes half-steps.This field only exists given thelatencyStats: { histograms: true } option. Empty ranges witha zero count are omitted from the output.Each document bears the following fields:
Field NameDescription
microsA 64-bit integer giving the inclusiveupper time bound of the current latency range inmicroseconds.The document’s range spans between the previous document’smicros value, exclusive, and this document’smicros value, inclusive.
countA 64-bit integer giving the number ofoperations with latency less than or equal to micros.

For example, if collStats returns the following histogram:

  1. histogram: [
  2.   { micros: NumberLong(1), count: NumberLong(10) },
  3.   { micros: NumberLong(2), count: NumberLong(1) },
  4.   { micros: NumberLong(4096), count: NumberLong(1) },
  5.   { micros: NumberLong(16384), count: NumberLong(1000) },
  6.   { micros: NumberLong(49152), count: NumberLong(100) }
  7. ]

This indicates that there were:

  • 10 operations taking 1 microsecond or less,
  • 1 operation in the range (1, 2] microseconds,
  • 1 operation in the range (3072, 4096] microseconds,
  • 1000 operations in the range (12288, 16384], and
  • 100 operations in the range (32768, 49152].

For example, if you run $collStats with the latencyStats: {} optionon a matrices collection:

  1. db.matrices.aggregate( [ { $collStats: { latencyStats: { histograms: true } } } ] )

This query returns a result similar to the following:

  1. { "ns" : "test.matrices",
  2.   "host" : mongo.example.net:27017",
  3.   "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  4.   "latencyStats" :
  5.     { "reads" :
  6.         { "histogram" : [
  7.             { "micros" : NumberLong(16),
  8.               "count" : NumberLong(3) },
  9.             { "micros" : NumberLong(32),
  10.               "count" : NumberLong(1) },
  11.             { "micros" : NumberLong(128),
  12.               "count" : NumberLong(1) } ],
  13.           "latency" : NumberLong(264),
  14.           "ops" : NumberLong(5) },
  15.       "writes" :
  16.         { "histogram" : [
  17.             { "micros" : NumberLong(32),
  18.               "count" : NumberLong(1) },
  19.             { "micros" : NumberLong(64),
  20.               "count" : NumberLong(3) },
  21.             { "micros" : NumberLong(24576),
  22.               "count" : NumberLong(1) } ],
  23.           "latency" : NumberLong(27659),
  24.           "ops" : NumberLong(5) },
  25.       "commands" :
  26.         { "histogram" : [
  27.             {
  28.                "micros" : NumberLong(196608),
  29.                "count" : NumberLong(1)
  30.             }
  31.           ],
  32.           "latency" : NumberLong(0),
  33.           "ops" : NumberLong(0) },
  34.       "transactions" : {
  35.          "histogram" : [ ],
  36.          "latency" : NumberLong(0),
  37.          "ops" : NumberLong(0)
  38.       }
  39.     }
  40. }

storageStats Document

The storageStats embedded document only exists in the output if youspecify the storageStats option.

The contents of this document are dependent on the storage engine in use.See Output for a reference on this document.

For example, if you run $collStats with the storageStats: {}option on a matrices collection using the WiredTiger Storage Engine:

  1. db.matrices.aggregate( [ { $collStats: { storageStats: { } } } ] )

This query returns a result similar to the following:

  1. {
  2.   "ns" : "test.matrices",
  3.   "host" : mongo.example.net:27017",
  4.   "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  5.   "storageStats" : {
  6.     "size" : 608500363,
  7.     "count" : 1104369,
  8.     "avgObjSize" : 550,
  9.     "storageSize" : 352878592,
  10.     "capped" : false,
  11.     "wiredTiger" : {
  12.       ...
  13.     },
  14.     "nindexes" : 2,
  15.     "indexDetails" : {
  16.       ...
  17.     },
  18.     "indexBuilds" : [    // Starting in MongoDB 4.2
  19.        "_id_1_abc_1"
  20.     ],
  21.     "totalIndexSize" : 260337664,
  22.     "indexSizes" : {
  23.       "_id_" : 9891840,
  24.       "_id_1_abc_1" : 250445824
  25.     },
  26.     "scaleFactor" : 1    // Starting in MongoDB 4.2
  27.   }
  28. }

Performing $collStats with the storageStats option on aview results in an error.

count Field

New in version 3.6.

The count field only exists in the output if you specify thecount option.

For example, if you run $collStats with the count: {} option ona matrices collection:

  1. db.matrices.aggregate( [ { $collStats: { count: { } } } ] )

The query returns a result similar to the following:

  1. {
  2.   "ns" : "test.matrices",
  3.   "host" : mongo.example.net:27017",
  4.   "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  5.   "count" : 1103869
  6. }

Note

The count is based on the collection’s metadata, which provides afast but sometimes inaccurate count for sharded clusters.

The total number of documents in the collection is also available asstorageStats.count when storageStats: {} is specified. For moreinformation, see storageStats Document.

$collStats on Sharded Collections

$collStats outputs one document per shard when run onsharded collections. Eachoutput document contains a shard field with the name of the shardthe document corresponds to.

For example, if you run $collStats on a sharded collection with thecount: {} option on a collection named matrices:

  1. db.matrices.aggregate( [ { $collStats: { count: { } } } ] )

The query returns a result similar to the following:

  1. {
  2.   "ns" : "test.matrices",
  3.   "shard" : "s1",
  4.   "host" : "s1-mongo1.example.net:27017",
  5.   "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  6.   "count" : 661705
  7. }
  8. {
  9.   "ns" : "test.matrices",
  10.   "shard" : "s2",
  11.   "host" : "s2-mongo1.example.net:27017",
  12.   "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  13.   "count" : 442164
  14. }

See also

collStats, db.collection.stats()