collStats（数据库命令）

定义

collStats

自版本 6.2 起已弃用。

在 6.2 版本及更高版本中，使用 $collStats 聚合阶段。

collStats 命令会返回给定集合的各种存储统计数据。

提示

In mongosh, this command can also be run through the stats() helper method. Specific fields in the collStats output can be accessed using the dataSize(), estimatedDocumentCount(), isCapped(), latencyStats(), storageSize(), totalIndexSize(), and totalSize() helper methods.

Helper methods are convenient for mongosh users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.

要运行 collStats，请使用 db.runCommand( { <command> } ) 方法。

兼容性

此命令可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

该命令具有以下语法：

db.runCommand(
   {
     collStats: <string>,
     scale: <int>
   }
)

命令字段

该命令接受以下字段：

字段	类型	说明
`collStats`	字符串	目标集合的名称。
`scale`	int	可选。各种尺寸数据的比例因子（在字段名称中指定测量单位的尺寸除外）。该值默认为 1，以字节为单位返回尺寸数据。要显示千字节而不是字节，请指定 `1024` 的 `scale` 值。如果指定了非整数比例因子，MongoDB 将使用该因子的整数部分。例如，如果指定比例因子为 `1023.999`，MongoDB 将使用 `1023` 作为比例因子。比例因子会将受影响的大小值四舍五入为整数。

行为

日志校订

使用 Queryable Encryption 时，$collStats 输出会编辑加密集合的某些信息：

输出省略了 "queryExecStats"
输出省略了 "latencyStats"
如果显示，输出将编辑 "WiredTiger" 以只包含 url 字段。

缩放的大小

除非指标名称另有指定（例如 "bytes currently in the cache"），否则与大小相关的值以字节为单位显示，并且可以被 scale 覆盖。

比例因子会将受影响的大小值四舍五入为整数。

意外关闭后的准确性

当使用 Wired Tiger 存储引擎时，如果 mongod 发生非正常关闭，collStats 报告的大小统计信息可能会不准确。

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

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

非正常关闭后：

validate updates the count statistic in the collStats output with the latest value.
Other statistics like the number of documents inserted or removed in the collStats output are estimates.

进行中的索引

collStats 包括有关当前正在构建的索引的信息。有关详细信息，请参阅：

collStats.nindexes
collStats.indexDetails
collStats.indexBuilds
collStats.totalIndexSize
collStats.indexSizes

副本集节点状态限制

要在副本集节点上运行，collStats 操作要求节点处于 PRIMARY 或 SECONDARY 状态。如果该节点处于其他状态，如 STARTUP2，则操作错误。

不存在的集合

If you run collStats for a non-existent collection, the command might return 0 values in the output fields instead of an error. This behavior depends on your database implementation.

For an example of this behavior, see Example.

例子

本页上的示例使用sample_mflix示例数据集中的数据。有关如何将此数据集加载到自管理MongoDB 部署中的详细信息，请参阅加载示例数据集。如果对示例数据库进行了任何修改，则可能需要删除并重新创建数据库才能运行本页上的示例。

以下操作将对 movies 集合运行 collStats 命令，并指定 scale 为 1024 字节：

db.runCommand( { collStats : "movies", scale: 1024 } )

{
  ok: 1,
  capped: false,
  ns: 'sample_mflix.movies',
  size: ...,
  count: 21349,
  avgObjSize: 1598,
  storageSize: ...,
  nindexes: 2,
  totalIndexSize: ...,
  totalSize: ...,
  indexSizes: {
    _id_: ...,
    cast_text_fullplot_text_genres_text_title_text: ...
  },
  scaleFactor: 1024
}

The following operation runs the collStats command on a non-existent collection:

db.runCommand( { collStats : "nonExistentCollection" } )

{
  ns: 'sample_mflix.nonExistentCollection',
  size: 0,
  count: 0,
  numOrphanDocs: 0,
  storageSize: 0,
  totalSize: 0,
  nindexes: 0,
  totalIndexSize: 0,
  indexDetails: {},
  indexSizes: {},
  scaleFactor: 1,
  ok: 1
}

输出

以下文档提供 collStats 输出的表示形式。根据集合和存储引擎的配置，输出字段可能会有所不同。

{
  "ns" : <string>,
  "size" : <number>,
  "timeseries" : {
     "bucketsNs" : <bucketName>,
     "bucketCount" : <number>,
     "avgBucketSize" : <number>,
     "numBucketInserts" : <number>,
     "numBucketUpdates" : <number>,
     "numBucketsOpenedDueToMetadata" : <number>,
     "numBucketsClosedDueToCount" : <number>,
     "numBucketsClosedDueToSize" : <number>,
     "numBucketsClosedDueToTimeForward" : <number>,
     "numBucketsClosedDueToTimeBackward" : <number>,
     "numBucketsClosedDueToMemoryThreshold" : <number>,
     "numCommits" : <number>,
     "numWaits" : <number>,
     "numMeasurementsCommitted" : <number>,
     "avgNumMeasurementsPerCommit": <number>
  },
  "count" : <number>,
  "avgObjSize" : <number>,
  "numOrphanDocs" : <number>,      // Available starting in MongoDB 6.0
  "storageSize" : <number>,
  "freeStorageSize" : <number>,
  "capped" : <boolean>,
  "max" : <number>,
  "maxSize" :  <number>,
  "wiredTiger" : {
     "metadata" : {
        "formatVersion" : <num>
     },
     "creationString" : <string>
     "type" :  <string>,
     "uri" :  <string>,
     "LSM" : {
        "bloom filter false positives" : <number>,
        "bloom filter hits" : <number>,
        "bloom filter misses" : <number>,
        "bloom filter pages evicted from cache" : <number>,
        "bloom filter pages read into cache" : <number>,
        "bloom filters in the LSM tree" : <number>,
        "total size of bloom filters" : <number>,
        "chunks in the LSM tree" : <number>,
        "highest merge generation in the LSM tree" : <number>,
        "queries that could have benefited from a Bloom filter that did not exist" : <number>,
        "sleep for LSM checkpoint throttle" : <number>,
        "sleep for LSM merge throttle" : <number>
        "total size of bloom filters" : <number>
     },
     "block-manager" : {
         "allocations requiring file extension" : <number>,
         "blocks allocated" : <number>,
         "blocks freed" : <number>,
         "checkpoint size" : <number>,
         "file allocation unit size" : <number>,
         "file bytes available for reuse" : <number>,
         "file magic number" : <number>,
         "file major version number" : <number>,
         "file size in bytes" : <number>,
         "minor version number" : <number>
     },
     "btree" : {
         "btree checkpoint generation" : <number>,
         "column-store fixed-size leaf pages" : <number>,
         "column-store internal pages" : <number>,
         "column-store variable-size RLE encoded values" : <number>,
         "column-store variable-size deleted values" : <number>,
         "column-store variable-size leaf pages" : <number>,
         "fixed-record size" : <number>,
         "maximum internal page key size" : <number>,
         "maximum internal page size" : <number>,
         "maximum leaf page key size" : <number>,
         "maximum leaf page size" : <number>,
         "maximum leaf page value size" : <number>,
         "maximum tree depth" : <number>,
         "number of key/value pairs" : <number>,
         "overflow pages" : <number>,
         "pages rewritten by compaction" : <number>,
         "row-store empty values" : <number>,
         "row-store internal pages" : <number>,
         "row-store leaf pages" : <number>
     },
     "cache" : {
        "bytes currently in the cache" : <number>,
        "bytes dirty in the cache cumulative" : <number>,
        "bytes read into cache" : <number>,
        "bytes written from cache" : <number>,
        "checkpoint blocked page eviction" : <number>,
        "data source pages selected for eviction unable to be evicted" : <number>,
        "eviction walk passes of a file" : <number>,
        "eviction walk target pages histogram - 0-9" : <number>,
        "eviction walk target pages histogram - 10-31" : <number>,
        "eviction walk target pages histogram - 128 and higher" : <number>,
        "eviction walk target pages histogram - 32-63" : <number>,
        "eviction walk target pages histogram - 64-128" : <number>,
        "eviction walks abandoned" : <number>,
        "eviction walks gave up because they restarted their walk twice" : <number>,
        "eviction walks gave up because they saw too many pages and found no candidates" : <number>,
        "eviction walks gave up because they saw too many pages and found too few candidates" : <number>,
        "eviction walks reached end of tree" : <number>,
        "eviction walks started from root of tree" : <number>,
        "eviction walks started from saved location in tree" : <number>,
        "hazard pointer blocked page eviction" : <number>,
        "in-memory page passed criteria to be split" : <number>,
        "in-memory page splits" : <number>,
        "internal pages evicted" : <number>,
        "internal pages split during eviction" : <number>,
        "leaf pages split during eviction" : <number>,
        "modified pages evicted" : <number>,
        "overflow pages read into cache" : <number>,
        "page split during eviction deepened the tree" : <number>,
        "page written requiring cache overflow records" : <number>,
        "pages read into cache" : <number>,
        "pages read into cache after truncate" : <number>,
        "pages read into cache after truncate in prepare state" : <number>,
        "pages read into cache requiring cache overflow entries" : <number>,
        "pages requested from the cache" : <number>,
        "pages seen by eviction walk" : <number>,
        "pages written from cache" : <number>,
        "pages written requiring in-memory restoration" : <number>,
        "tracked dirty bytes in the cache" : <number>,
        "unmodified pages evicted" : <number>
     },
     "cache_walk" : {
        "Average difference between current eviction generation when the page was last considered" : <number>,
        "Average on-disk page image size seen" : <number>,
        "Average time in cache for pages that have been visited by the eviction server" : <number>,
        "Average time in cache for pages that have not been visited by the eviction server" : <number>,
        "Clean pages currently in cache" : <number>,
        "Current eviction generation" : <number>,
        "Dirty pages currently in cache" : <number>,
        "Entries in the root page" : <number>,
        "Internal pages currently in cache" : <number>,
        "Leaf pages currently in cache" : <number>,
        "Maximum difference between current eviction generation when the page was last considered" : <number>,
        "Maximum page size seen" : <number>,
        "Minimum on-disk page image size seen" : <number>,
        "Number of pages never visited by eviction server" : <number>,
        "On-disk page image sizes smaller than a single allocation unit" : <number>,
        "Pages created in memory and never written" : <number>,
        "Pages currently queued for eviction" : <number>,
        "Pages that could not be queued for eviction" : <number>,
        "Refs skipped during cache traversal" : <number>,
        "Size of the root page" : <number>,
        "Total number of pages currently in cache" : <number>
     },
     "compression" : {
        "compressed page maximum internal page size prior to compression" : <number>,
        "compressed page maximum leaf page size prior to compression " : <number>,
        "compressed pages read" : <number>,
        "compressed pages written" : <number>,
        "page written failed to compress" : <number>,
        "page written was too small to compress" : 1
     },
     "cursor" : {
        "bulk loaded cursor insert calls" : <number>,
        "cache cursors reuse count" : <number>,
        "close calls that result in cache" : <number>,
        "create calls" : <number>,
        "insert calls" : <number>,
        "insert key and value bytes" : <number>,
        "modify" : <number>,
        "modify key and value bytes affected" : <number>,
        "modify value bytes modified" : <number>,
        "next calls" : <number>,
        "open cursor count" : <number>,
        "operation restarted" : <number>,
        "prev calls" : <number>,
        "remove calls" : <number>,
        "remove key bytes removed" : <number>,
        "reserve calls" : <number>,
        "reset calls" : <number>,
        "search calls" : <number>,
        "search near calls" : <number>,
        "truncate calls" : <number>,
        "update calls" : <number>,
        "update key and value bytes" : <number>,
        "update value size change" : <num>
     },
     "reconciliation" : {
        "dictionary matches" : <number>,
        "fast-path pages deleted" : <number>,
        "internal page key bytes discarded using suffix compression" : <number>,
        "internal page multi-block writes" : <number>,
        "internal-page overflow keys" : <number>,
        "leaf page key bytes discarded using prefix compression" : <number>,
        "leaf page multi-block writes" : <number>,
        "leaf-page overflow keys" : <number>,
        "maximum blocks required for a page" : <number>,
        "overflow values written" : <number>,
        "page checksum matches" : <number>,
        "page reconciliation calls" : <number>,
        "page reconciliation calls for eviction" : <number>,
        "pages deleted" : <number>
     },
     "session" : {
        "object compaction" : <number>,
     },
     "transaction" : {
        "update conflicts" : <number>
     }
  },
  "nindexes" : <number>,
  "indexDetails" : {
     "_id_" : {
        "metadata" : {
           "formatVersion" : <number>
        },
        ...
     },
     ...
  },
  "indexBuilds" : [
     <string>,
  ],
  "totalIndexSize" : <number>,
  "totalSize" : <number>,
  "indexSizes" : {
          "_id_" : <number>,
          "<indexName>" : <number>,
          ...
  },
  "scaleFactor" : <number>
  "ok" : <number>
}

collStats.ns: 当前集合的命名空间，遵循 [database].[collection] 格式。

collStats.size

The total uncompressed size in memory of all records in a collection. The size does not include the size of any indexes associated with the collection, which the totalIndexSize field reports.

scale 参数会影响此值。数据压缩不会影响此值。

collStats.timeseries

timeseries appears when you run the collStats command on a time series collection.

本文档包含供内部诊断使用的数据。

collStats.count: 此集合中对象或文档的数量。

collStats.avgObjSize: 集合中的对象的平均大小。scale 参数不会影响此值。

collStats.numOrphanDocs: 集合中孤立文档的数量。
6.0版本新增。

collStats.storageSize

分配给该集合用于文档存储的总存储量。scale 参数会影响此值。

If collection data is compressed (which is the default for WiredTiger), the storage size reflects the compressed size and may be smaller than the value for collStats.size.

storageSize does not include index size. See totalIndexSize for index sizing.

collStats.freeStorageSize

不用于内存存储引擎

可重复使用的存储量。scale 参数会影响该值。

仅当存储空间可供重复使用时，该字段才可用（即大于零）。

collStats.nindexes

集合上的索引数量。所有集合都至少有一个 _id 字段索引。

nindexes 包括计数中当前正在构建的索引。

collStats.indexDetails

一份文档：针对集合中每个索引，报告来自 WiredTiger 存储引擎的数据。其他存储引擎会返回一份空文档。

此文档中的字段是索引的名称，而值本身是包含存储引擎所提供的索引统计信息的文档。这些统计信息供内部诊断使用。

indexDetails 包含有关当前正在构建的索引的详细信息，包括警告和错误。

collStats.indexBuilds: An array that contains the names of the indexes that are currently being built on the collection. Once an index build completes, the index does not appear in the indexBuilds.

collStats.totalIndexSize

所有索引使用的磁盘空间总和。scale 参数会影响此值。

如果索引使用前缀压缩（即 default for WiredTiger），则在计算总数时，返回的大小将反映此类索引的压缩大小。

totalIndexSize 包括总大小中当前正在构建的索引。

collStats.totalSize: The sum of the storageSize and totalIndexSize. The scale argument affects this value.

collStats.indexSizes

此字段指定集合上每个现有索引的键和大小。scale 参数会影响此值。

如果索引使用了前缀压缩（即 default for WiredTiger），返回的大小将反映压缩后的大小。

indexSizes 包括当前所构建索引的大小。

collStats.scaleFactor

该命令使用的 scale 值。

如果指定了非整数比例因子，MongoDB 将使用该因子的整数部分。例如，如果指定比例因子为 1023.999，MongoDB 将使用 1023 作为比例因子。

collStats.capped: 如果集合为固定大小集合，该字段将为“true”。

collStats.max: 显示固定大小集合中可能存在的最大文档数。

collStats.maxSize: 显示固定大小集合的最大大小。

collStats.wiredTiger

wiredTiger only appears when using the WiredTiger storage engine. When using Queryable Encryption, WiredTiger data is redacted to only the url field.

本文档包含由 WiredTiger 引擎直接报告的数据以及供内部诊断使用的其他数据。

collStats.inMemory

inMemory 仅在使用内存存储引擎时出现。

本文档包含由存储引擎直接报告的数据以及供内部诊断使用的其他数据。