On this page

• Definition
• Behavior

Definition

$collStats

New in version 3.4.

Returns statistics regarding a collection or view.

The $collStats stage has the following prototype form:

copy

{
  $collStats:
    {
      latencyStats: { histograms: <boolean> },
      storageStats: {},
      count: {}
    }
}

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

Field Name	Description
latencyStats	Adds latency statistics to the return document.
latencyStats.histograms	Adds latency histogram information to the embedded documents in latencyStats if true.
storageStats	Adds storage statistics to the return document.
count	Adds the total number of documents in the collection to the return document. New in version 3.6.

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

Field Name	Description
ns	The namespace of the requested collection or view.
shard	The name of the shard the output document corresponds to. Only present when $collStats runs on a sharded cluster. Both sharded and non-sharded collections will produce this field. New in version 3.6.
host	The hostname and port of the mongod process which produced the output document. New in version 3.6.
localTime	The current time on the MongoDB server, expressed as UTC milliseconds since the Unix epoch.
latencyStats	A collection of statistics related to request latency for a collection or view. See latencyStats Document for details on this document. Only present when the latencyStats: {} option is specified.
storageStats	A collection of statistics related to a collection’s storage engine. See storageStats Document for details on this document. Only present when the storageStats: {} option is specified. Returns an error if applied to a view.
count	The total number of documents in the collection. This data is also available in storageStats.count. Only present when the count: {} option is specified. Returns an error if applied to a view.

Behavior

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

histogram: [
  { micros: NumberLong(1), count: NumberLong(10) },
  { micros: NumberLong(2), count: NumberLong(1) },
  { micros: NumberLong(4096), count: NumberLong(1) },
  { micros: NumberLong(16384), count: NumberLong(1000) },
  { micros: NumberLong(49152), count: NumberLong(100) }
]

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

{ "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "latencyStats" :
    { "reads" :
        { "histogram" : [
            { "micros" : NumberLong(16),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(128),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(264),
          "ops" : NumberLong(5) },
      "writes" :
        { "histogram" : [
            { "micros" : NumberLong(32),
              "count" : NumberLong(1) },
            { "micros" : NumberLong(64),
              "count" : NumberLong(3) },
            { "micros" : NumberLong(24576),
              "count" : NumberLong(1) } ],
          "latency" : NumberLong(27659),
          "ops" : NumberLong(5) },
      "commands" :
        { "histogram" : [ ],
          "latency" : NumberLong(0),
          "ops" : NumberLong(0) }
    }
}

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

{
  "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2017-10-06T19:43:56.599Z"),
  "storageStats" : {
    "size" : 608500363,
    "count" : 1104369,
    "avgObjSize" : 550,
    "storageSize" : 352878592,
    "capped" : false,
    "wiredTiger" : {
      ...
    },
    "nindexes" : 1,
    "indexDetails" : {
      ...
    },
    "totalIndexSize" : 9891840,
    "indexSizes" : {
      "_id_" : 9891840
    }
  }
}

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

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

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

{
  "ns" : "test.matrices",
  "shard" : "s1",
  "host" : "s1-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 661705
}
{
  "ns" : "test.matrices",
  "shard" : "s2",
  "host" : "s2-mongo1.example.net:27017",
  "localTime" : ISODate("2017-10-06T15:14:21.258Z"),
  "count" : 442164
}