$collStats (aggregation)

On this page

Definition

  • $collStats
    • New in version 3.4.

Returns statistics regarding a collection or view.

The $collStats stage has the following prototype form:

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

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

Field NameDescription
latencyStatsAdds latency statistics to the return document.
latencyStats.histogramsAdds latency histogram information to the embedded documents in latencyStats if true .
storageStatsAdds storage statistics to the return document.
countAdds 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 NameDescription
nsThe 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. Both sharded and non-sharded collections will produce this field.
New in version 3.6.
hostThe hostname and port of the mongod process which produced the output document.
New in version 3.6.
localTimeThe current time on the MongoDB server, expressed as UTC milliseconds since the Unix epoch.
latencyStatsA 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.
storageStatsA 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.
countThe 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.

latencyStats Document

The latencyStats embedded document only exists in the output if you 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 the following fields:

Field NameDescription
latencyA long giving the total combined latency in microseconds.
opsA long giving the total number of operations 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. For upper values between 2048 microseconds and roughly 1 second, the histogram includes half-steps.
This field only exists given the latencyStats: { histograms: true } option. Empty ranges with a zero count are omitted from the output.
Each document bears the following fields:
| Field Name | Description |
| micros | A long giving the inclusive upper time bound of the current latency range in microseconds.
The document’s range spans between the previous document’s micros value, exclusive, and this document’s micros value, inclusive. |
| count | A long giving the number of operations with latency less than or equal to micros . |
For example, if collStats returns the following histogram:
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) }
]
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: {} option on a matrices collection:

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

This query returns a result similar to the following:

{ "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) }
    }
}

storageStats Document

The storageStats embedded document only exists in the output if you specify 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:

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

This query returns a result similar to the following:

{
  "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
    }
  }
}

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

count Field

New in version 3.6.

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

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

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

The query returns a result similar to the following:

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

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

$collStats on Sharded Collections

$collStats outputs one document per shard when run on sharded collections. Each output document contains a shard field with the name of the shard the document corresponds to.

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

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

The query returns a result similar to the following:

{
  "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
}