$collStats（聚合）

在此页面上

定义

行为

定义

$collStats

返回有关集合或视图的统计信息。

$collStats 阶段具有以下原型形式：

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

$collStats 阶段接受带有以下可选字段的参数文档：

字段名称	说明
`latencyStats`	将延迟统计数据添加到返回文档中。
`latencyStats.histograms`	如果为 `true`，将延迟直方图信息添加到 `latencyStats` 中的嵌入文档。
`storageStats`	将存储统计数据添加到返回文档中。指定一个空文档（即 `storageStats: {}`）对各种大小的数据使用默认比例因子 1。比例因子 1 显示返回的大小，以字节为单位。指定比例因子（即 `storageStats: { scale: <number> }`）对各种大小数据使用指定的比例因子。例如，要显示千字节而不是字节，请指定比例值 1024。如果指定了非整数比例因子，MongoDB 将使用该因子的整数部分。例如，如果指定比例因子为 `1023.999`，MongoDB 将使用 `1023` 作为比例因子。比例因子不会影响在字段名称中指定测量单位的大小，例如 `"bytes currently in the cache"`。
`count`	将集合中的文档总数添加到返回文档中。该计数基于集合的元数据，它为分片集群提供快速但有时不准确的计数。请参阅 `count` 字段
`queryExecStats`	将查询执行统计数据添加到返回文档中。

对于副本集集合集群中的非分片集合， $collStats输出单个文档。对于分片的集合， $collStats会为每个分片片输出一个文档。输出文档包括以下字段：

字段名称	说明
`ns`	请求的集合或视图的命名空间。
`shard`	输出文档对应的分片的名称。仅当 `$collStats` 在分片集群上运行时才出现。分片和非分片集合都会产生这个字段。
`host`	生成输出文档的 `mongod` 进程的主机名和端口。
`localTime`	MongoDB 服务器上的当前时间，表示为自 UNIX 纪元以来的 UTC 毫秒数。
`latencyStats`	与集合或视图的请求延迟有关的统计信息。有关此文档的详细信息，请参阅 `latencyStats` 文档。仅当指定了 `latencyStats: {}` 选项时显示。
`storageStats`	与集合的存储引擎相关的统计数据。有关此文档的详细信息，请参阅 `storageStats` 文档。各种尺寸数据按指定的比例因子缩放（在字段名称中指定测量单位的尺寸除外）。仅当指定了 `storageStats` 选项时显示。如果应用于视图，则返回错误。
`count`	集合中的文档总数。此数据也可在 `storageStats.count` 中找到。该计数基于集合的元数据，它为分片集群提供快速但有时不准确的计数。仅当指定了 `count: {}` 选项时显示。如果应用于视图，则返回错误。
`queryExecStats`	与集合的查询执行相关的统计数据。仅当指定了 `queryExecStats: {}` 选项时显示。如果应用于视图，则返回错误。

行为

$collStats 必须是聚合管道中的第一阶段，否则管道将返回错误。

意外关闭后的准确性

使用 Wired mongod Tiger存储引擎的非正常关闭后，$collStats 报告的大小和计数统计信息可能不准确。

偏差的大小取决于在最后一个检查点和非正常关闭之间执行的插入、更新或删除操作的次数。检查点通常每 60 秒出现一次。但是，如果 mongod 实例使用了非默认的 --syncdelay 设置，则检查点出现的次数可能会增多或减少。

在 mongod 的每个集合上运行 validate，以在非正常关闭之后恢复统计信息。

非正常关闭后：

validate使用最新值更新 collStats输出中的计数统计数据。
其他统计信息（例如在 collStats 输出中插入或删除的文档数量）均为估计值。

事务

$collStats 不允许在事务中使用。

`latencyStats` 文档

如果指定 latencyStats 选项，则 latencyStats 嵌入文档仅存在于输出中。

字段名称	说明
`reads`	读取请求的延迟统计信息。
`writes`	写入请求的延迟统计数据。
`commands`	数据库命令的延迟统计信息。

其中每个字段都包含一个包含以下字段的嵌入文档：

字段名称

说明

latency

一个 64 位整数，以微秒为单位表示总组合延迟。

ops

一个 64 位整数，表示自启动以来对集合执行的操作总数。

histogram

嵌入式文档大量，每个文档代表一个延迟范围。每个文档的覆盖范围是前一个文档范围的两倍。对于介于2048微秒到大约1秒之间的较低值，直方图包括半步。

此字段仅在给定 latencyStats: { histograms: true } 选项时存在。输出中将省略带有零 count 的空范围。

每个文档都包含以下字段：

字段名称	说明
`micros`	一个64位整数，给出当前延迟范围的包含时间下限（以微秒为单位）。文档的范围介于上一文档的 `micros` 值（不含）和本文档的 `micros` 值（含）之间。
`count`	一个 64 位整数，表示延迟小于或等于 `micros` 的操作次数。

例如，如果 collStats 返回以下直方图：

histogram: [
  { micros: NumberLong(0), 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) }
]

这表明：

10操作用时2微秒或更短
1操作，范围[ 2 , 4 ) 微秒
1操作，范围[ 4096 , 6144 ) 微秒
在 [ 16384 , 24576 ) 微秒范围执行1000次操作
在 [ 49152 , 65536 ) 微秒范围执行100次操作

[1]	此页上的 `(` 符号表示表示该值不包含在内。本页中的 `]` 符号表示该值包含在内。

例如，在 matrices 集合上运行带有 latencyStats: {} 选项的 $collStats：

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

`storageStats` 文档

如果指定 storageStats 选项，则 storageStats 嵌入文档仅存在于输出中。

本文档的内容取决于所使用的存储引擎。有关本文档的参考，请参阅输出。

例如，如果您使用 WiredTiger 存储引擎在 matrices 集合上运行带有 storageStats: {} 选项的 $collStats：

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,
    "capped" : false,
    "wiredTiger" : {
      ...
    },
    "nindexes" : 2,
    "indexDetails" : {
      ...
    },
    "indexBuilds" : [    // Starting in MongoDB 4.2
       "_id_1_abc_1"
    ],
    "totalIndexSize" : 260337664,
    "totalSize" : 613216256,
    "indexSizes" : {
      "_id_" : 9891840,
      "_id_1_abc_1" : 250445824
    },
    "scaleFactor" : 1    // Starting in MongoDB 4.2
  }
}

有关本文档的参考，请参阅输出。

注意

进行中的索引

从 MongoDB 4.2 开始，返回的storageStats包含有关正在构建的索引的信息。有关详细信息，请参阅：

在视图上使用storageStats选项执行$collStats会导致错误。

`count` 字段

如果指定 count 选项，则 count 字段仅存在于输出中。

例如，在 matrices 集合上运行带有 count: {} 选项的 $collStats：

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

查询返回的结果如下：

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

注意

该计数基于集合的元数据，它为分片集群提供快速但有时不准确的计数。

当指定 storageStats: {} 时，集合中的文档总数也可以作为 storageStats.count 可用。有关更多信息，请参阅 storageStats 文档。

`queryExecStats` 文档

如果指定 queryExecStats 选项，则 queryExecStats 嵌入文档仅存在于输出中。

collectionScans字段包含一个包含以下字段的嵌入式文档：

字段名称	说明
`total`	一个 64 位整数，表示执行collection扫描的查询总数。总数包括使用和未使用可追加游标的查询。
`nonTailable`	一个 64 位整数，给出执行未使用可追加游标的集合扫描的查询数量。

例如，在 matrices 集合上运行带有 queryExecStats: {} 选项的 $collStats：

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

`$collStats` 在分片集合上

$collStats 在分片集合上运行时，将为每个分片输出一个文档。每个输出文档都包含一个 shard 字段，其中包含该文档对应的分片的名称。

例如，如果您在分片集合上运行 $collStats，并在名为 matrices 的集合上使用 count: {} 选项：

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
}

提示

另请参阅：

后退

$changeStreamSplitLargeEvent

来年

$count

定义

行为

意外关闭后的准确性

事务

latencyStats 文档

storageStats 文档

注意

进行中的索引

count 字段

注意

queryExecStats 文档

$collStats 在分片集合上

提示

另请参阅：

`latencyStats` 文档

`storageStats` 文档

`count` 字段

`queryExecStats` 文档

`$collStats` 在分片集合上