$collStats (aggregation)¶

Definition定义¶

$collStats¶

New in version 3.4.版本3.4中的新功能。

Returns statistics regarding a collection or view.返回有关集合或视图的统计信息。

The $collStats stage has the following prototype form:$collStats阶段具有以下原型形式：

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

The $collStats stage accepts an argument document with the following optional fields:$collStats阶段接受带有以下可选字段的参数文档：

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.如果为true，则向latencyStats中的嵌入文档添加延迟直方图信息。
storageStats	Adds storage statistics to the return document.将存储统计信息添加到返回文档中。 Specify an empty document (i.e. storageStats: {}) to use the default scale factor of 1 for the various size data. 指定一个空文档（即storageStats:{}），对各种大小的数据使用默认的比例因子1。Scale factor of 1 displays the returned sizes in bytes.比例因子1以字节为单位显示返回的大小。 Specify the scale factor (i.e. storageStats: { scale: <number> }) to use the specified scale factor for the various size data. 指定比例因子（即storageStats: { scale: <number> }），以便对各种大小的数据使用指定的比例因子。For example, to display kilobytes rather than bytes, specify a scale value of 1024.例如，要显示千字节而不是字节，请指定1024的刻度值。 If you specify a non-integer scale factor, MongoDB uses the integer part of the specified factor. 如果指定非整数比例因子，MongoDB将使用指定因子的整数部分。For example, if you specify a scale factor of 1023.999, MongoDB uses 1023 as the scale factor.例如，如果指定比例因子1023.999，MongoDB将使用1023作为比例因子。 The scale factor does not affect those sizes that specify the unit of measurement in the field name, such as "bytes currently in the cache".比例因子不影响在字段名中指定度量单位的大小，例如"bytes currently in the cache"。
count	Adds the total number of documents in the collection to the return document.将集合中的文档总数添加到退货文档中。 Note The count is based on the collection’s metadata, which provides a fast but sometimes inaccurate count for sharded clusters.计数基于集合的元数据，这为分片集群提供了快速但有时不准确的计数。 See count Field请参阅计数字段 New in version 3.6.版本3.6中的新功能。
queryExecStats	Adds query execution statistics to the return document.向返回文档添加查询执行统计信息。 New in version 4.4.版本4.4中的新功能。

For a collection in a replica set or a non-sharded collection in a cluster, $collStats outputs a single document. 对于副本集中的集合或集群中的 非分片集合，$collStats输出单个文档。For a sharded collection, $collStats outputs one document per shard. 对于分片集合，$collStats会为每个分片输出一个文档。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. 仅当$collStats在分片集群上运行时出现。Both sharded and non-sharded collections will produce this field.分片集合和非分片集合都将产生此字段。 New in version 3.6.版本3.6中的新功能。
host	The hostname and port of the mongod process which produced the output document.生成输出文档的mongod进程的主机名和端口。 New in version 3.6.版本3.6中的新功能。
localTime	The current time on the MongoDB server, expressed as UTC milliseconds since the Unix epoch.MongoDB服务器上的当前时间，表示为自Unix纪元以来的UTC毫秒。
latencyStats	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.仅在指定latencyStats:{}选项时出现。
storageStats	Statistics related to a collection’s storage engine. 与集合的存储引擎相关的统计信息。See storageStats Document for details on this document.有关此文档的详细信息，请参阅storageStats文档。 The various size data is scaled by the specified factor (with the exception of those sizes that specify the unit of measurement in the field name).各种大小的数据按指定的因子进行缩放（在字段名中指定测量单位的大小除外）。 Only present when the storageStats option is specified.仅在指定storageStats选项时出现。 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.storageStats.count中也提供了这些数据。 Note The count is based on the collection’s metadata, which provides a fast but sometimes inaccurate count for sharded clusters.计数基于集合的元数据，这为分片集群提供了快速但有时不准确的计数。 Only present when the count: {} option is specified. 仅在指定了count:{}选项时出现。Returns an error if applied to a view.如果应用于视图，则返回错误。
queryExecStats	Statistics related to query execution for the collection.与集合的查询执行相关的统计信息。 Only present when the queryExecStats: {} option is specified. 仅在指定queryExecStats:{}选项时出现。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.$collStats必须是聚合管道中的第一个阶段，否则管道将返回错误。

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" : [
            {
               "micros" : NumberLong(196608),
               "count" : NumberLong(1)
            }
          ],
          "latency" : NumberLong(0),
          "ops" : NumberLong(0) },
      "transactions" : {
         "histogram" : [ ],
         "latency" : NumberLong(0),
         "ops" : NumberLong(0)
      }
    }
}

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

{
  "ns" : "test.matrices",
  "host" : mongo.example.net:27017",
  "localTime" : ISODate("2020-03-06T01:44:57.437Z"),
  "storageStats" : {
    "size" : 608500363,
    "count" : 1104369,
    "avgObjSize" : 550,
    "storageSize" : 352878592,
    "freeStorageSize" : 2490380,  // Starting in MongoDB 4.4
    "capped" : false,
    "wiredTiger" : {
      ...
    },
    "nindexes" : 2,
    "indexDetails" : {
      ...
    },
    "indexBuilds" : [    // Starting in MongoDB 4.2
       "_id_1_abc_1"
    ],
    "totalIndexSize" : 260337664,
    "totalSize" : 613216256,    // Starting in MongoDB 4.4
    "indexSizes" : {
      "_id_" : 9891840,
      "_id_1_abc_1" : 250445824
    },
    "scaleFactor" : 1    // Starting in MongoDB 4.2
  }
}

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: { queryExecStats: { } } } ] )

{
  "ns": "test.matrices",
  "host": "mongo.example.net:27017",
  "localTime": ISODate("2020-06-03T14:23:29.711Z"),
  "queryExecStats": {
      "collectionScans": {
          "total": NumberLong(33),
          "nonTailable": NumberLong(31)
      }
  }
}

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
}