db.collection.stats() (mongosh method)

Scaled Sizes

Unless otherwise specified by the metric name (such as "bytes currently in the cache"), values related to size are displayed in bytes and can be overridden by scale.

The scale factor rounds the affected size values to whole numbers.

Storage Engine

Depending on the storage engine, the data returned may differ. For details on the fields, see output details.

Accuracy after Unexpected Shutdown

After an unclean shutdown of a mongod using the Wired Tiger storage engine, count and size statistics reported by db.collection.stats() may be inaccurate.

The amount of drift depends on the number of insert, update, or delete operations performed between the last checkpoint and the unclean shutdown. Checkpoints usually occur every 60 seconds. However, mongod instances running with non-default --syncdelay settings may have more or less frequent checkpoints.

Run validate on each collection on the mongod to restore statistics after an unclean shutdown.

After an unclean shutdown:

• 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.

Replica Set Member State Restriction

To run on a replica set member, collStats operations require the member to be in PRIMARY or SECONDARY state. If the member is in another state, such as STARTUP2, the operation errors.

Index Filter Behavior

Filtering on indexDetails using either indexDetailsKey or indexDetailsName will only return a single matching index. If no exact match is found, indexDetails will show information on all indexes for the collection.

The indexDetailsKey field takes a document of the following form:

{ '<string>' : <value>, '<string>' : <value>, ... }

Where <string>> is the field that is indexed and <value> is either the direction of the index, or the special index type such as text or 2dsphere. See index types for the full list of index types.

Starting in MongoDB 8.0, use query settings instead of adding index filters. Index filters are deprecated starting in MongoDB 8.0.

Query settings have more functionality than index filters. Also, index filters aren't persistent and you cannot easily create index filters for all cluster nodes. To add query settings and explore examples, see setQuerySettings.

Unexpected Shutdown and Count

For MongoDB instances using the WiredTiger storage engine, after an unclean shutdown, statistics on size and count may off by up to 1000 documents as reported by collStats, dbStats, count. To restore the correct statistics for the collection, run validate on the collection.

In-Progress Indexes

The db.collection.stats() includes information on indexes currently being built. For details, see:

• collStats.nindexes

• collStats.indexDetails

• collStats.indexBuilds

• collStats.totalIndexSize

• collStats.indexSizes

Basic Stats Lookup

The following operation returns stats on the movies collection in the sample_mflix database:

db.movies.stats()

{
  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: 1
}

If you do not specify a scale parameter, all size values are in bytes.

Stats Lookup With Scale

The following operation returns the size values in kilobytes instead of bytes by specifying a scale of 1024:

db.movies.stats( { 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
}

Statistics Lookup With Index Details

The following operation returns an indexDetails field that contains information related to each of the indexes within the collection:

db.movies.stats( { indexDetails : true } )

{
  ok: 1,
  capped: false,
  ns: 'sample_mflix.movies',
  count: 21349,
  nindexes: 2,
  indexDetails: {
    _id_: ...,
    cast_text_fullplot_text_genres_text_title_text: ...
  },
  indexSizes: {
    _id_: ...,
    cast_text_fullplot_text_genres_text_title_text: ...
  },
  scaleFactor: 1
}

Statistics Lookup With Filtered Index Details

To filter the indexes in the indexDetails field, specify the index keys with the indexDetailsKey option or the index name with the indexDetailsName option. To discover the index keys and names, use db.collection.getIndexes().

Given the following index:

{
   "ns" : "sample_mflix.movies",
   "v" : 2,
   "key" : {
      "_fts" : "text",
      "_ftsx" : 1
   },
   "name" : "cast_text_fullplot_text_genres_text_title_text",
   "weights" : {
      "cast" : 1,
      "fullplot" : 1,
      "genres" : 1,
      "title" : 1
   },
   "default_language" : "english",
   "language_override" : "language",
   "textIndexVersion" : 3
}

The following operation filters the indexDetails document to a single index using the indexDetailsKey option.

db.movies.stats(
   {
      'indexDetails' : true,
      'indexDetailsKey' :
      {
         '_fts' : 'text',
         '_ftsx' : 1
      }
   }
)

The following operation filters the indexDetails document to a single index using the indexDetailsName option.

db.movies.stats(
   {
      'indexDetails' : true,
      'indexDetailsName' : 'cast_text_fullplot_text_genres_text_title_text'
   }
)

Both operations return the same output:

{
  ok: 1,
  capped: false,
  ns: 'sample_mflix.movies',
  count: 21349,
  nindexes: 2,
  indexDetails: {
    cast_text_fullplot_text_genres_text_title_text: ...
  },
  indexSizes: {
    _id_: ...,
    cast_text_fullplot_text_genres_text_title_text: ...
  },
  scaleFactor: 1
}

For an explanation of the output, see output details.