> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt # db.collection.stats() (mongosh method) **Important: mongosh Method** This page documents a [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) method. This is *not* the documentation for database commands or language-specific drivers, such as Node.js. For the database command, see the [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) command. For MongoDB API drivers, refer to the language-specific [MongoDB driver documentation.](https://www.mongodb.com/docs/drivers/) ## Definition Returns statistics about the collection. A [document](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-document) that contains statistics on the specified collection. See [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) for a breakdown of the returned statistics. **Note:** [`db.collection.stats()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.stats.md#mongodb-method-db.collection.stats) internally calls the [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats) aggregation stage by default. ## Syntax The method has the following format: ```javascript db.collection.stats({ scale: , // Optional indexDetails: , // Optional indexDetailsKey: , // Optional indexDetailsName: . // Optional }) ``` ## Fields | Field | Type | Description | | --- | --- | --- | | `scale` | number | Optional. The scale factor for the various size data. The `scale` defaults to 1 to return size data in bytes. To display kilobytes rather than bytes, specify a `scale` value of `1024`. If you specify a non-integer scale factor, MongoDB uses the integer part of the specified factor. For example, if you specify a scale factor of `1023.999`, MongoDB uses `1023` as the scale factor. Starting in version 4.2, the output includes the `scaleFactor` used to scale the size values. | | `indexDetails` | boolean | Optional. If `true`, [`db.collection.stats()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.stats.md#mongodb-method-db.collection.stats) returns [`index details`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexDetails) in addition to the collection stats. Only works for [WiredTiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger) storage engine. Defaults to `false`. | | `indexDetailsKey` | document | Optional. If `indexDetails` is `true`, you can use `indexDetailsKey` to filter index details by specifying the index key specification. Only the index that exactly matches `indexDetailsKey` will be returned. If no match is found, [`indexDetails`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexDetails) will display statistics for all indexes. Use [`getIndexes()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.getindexes.md#mongodb-method-db.collection.getIndexes) to discover index keys. You cannot use `indexDetailsKey` with `indexDetailsName`. | | `indexDetailsName` | string | Optional. If `indexDetails` is `true`, you can use `indexDetailsName` to filter index details by specifying the index `name`. Only the index name that exactly matches `indexDetailsName` will be returned. If no match is found, [`indexDetails`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexDetails) will display statistics for all indexes. Use [`getIndexes()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.getindexes.md#mongodb-method-db.collection.getIndexes) to discover index names. You cannot use `indexDetailsName` with `indexDetailsField`. | To specify just the `scale` factor, MongoDB supports the legacy format: ```javascript db.collection.stats() ``` ## Compatibility This method is available in deployments hosted in the following environments: - [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud **Note:** This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/) - [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB - [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB ## Behavior ### 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.](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) ### Accuracy after Unexpected Shutdown After an unclean shutdown of a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) using the [Wired Tiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md) storage engine, count and size statistics reported by [`db.collection.stats()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.stats.md#mongodb-method-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](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger-checkpoints) and the unclean shutdown. Checkpoints usually occur every 60 seconds. However, [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instances running with non-default [`--syncdelay`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--syncdelay) settings may have more or less frequent checkpoints. Run [`validate`](https://www.mongodb.com/docs/manual/reference/command/validate.md#mongodb-dbcommand-dbcmd.validate) on each collection on the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) to restore statistics after an unclean shutdown. After an unclean shutdown: - [`validate`](https://www.mongodb.com/docs/manual/reference/command/validate.md#mongodb-dbcommand-dbcmd.validate) updates the [count statistic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#std-label-collstat-count) in the [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) [output](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) with the latest value. - Other statistics like the number of documents inserted or removed in the [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) [output](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) are estimates. ### Replica Set Member State Restriction To run on a replica set member, [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) operations require the member to be in [`PRIMARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.PRIMARY) or [`SECONDARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.SECONDARY) state. If the member is in another state, such as [`STARTUP2`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.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: ```javascript { '' : , '' : , ... } ``` Where `>` is the field that is indexed and `` is either the direction of the index, or the special index type such as `text` or `2dsphere`. See [index types](https://www.mongodb.com/docs/manual/core/indexes/index-types.md#std-label-index-types) for the full list of index types. Starting in MongoDB 8.0, use query settings instead of adding [index filters](https://www.mongodb.com/docs/manual/core/query-plans.md#std-label-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`.](https://www.mongodb.com/docs/manual/reference/command/setquerysettings.md#mongodb-dbcommand-dbcmd.setQuerySettings) ### Unexpected Shutdown and Count For MongoDB instances using the [WiredTiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger) storage engine, after an unclean shutdown, statistics on size and count may off by up to 1000 documents as reported by [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats), [`dbStats`](https://www.mongodb.com/docs/manual/reference/command/dbstats.md#mongodb-dbcommand-dbcmd.dbStats), [`count`](https://www.mongodb.com/docs/manual/reference/command/count.md#mongodb-dbcommand-dbcmd.count). To restore the correct statistics for the collection, run [`validate`](https://www.mongodb.com/docs/manual/reference/command/validate.md#mongodb-dbcommand-dbcmd.validate) on the collection. ### In-Progress Indexes The [`db.collection.stats()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.stats.md#mongodb-method-db.collection.stats) includes information on indexes currently being built. For details, see: - [`collStats.nindexes`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.nindexes) - [`collStats.indexDetails`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexDetails) - [`collStats.indexBuilds`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexBuilds) - [`collStats.totalIndexSize`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.totalIndexSize) - [`collStats.indexSizes`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.indexSizes) ## Examples The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page. ### Basic Stats Lookup The following operation returns stats on the `movies` collection in the `sample_mflix` database: ```javascript db.movies.stats() ``` **Output:** ```javascript { 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`: ```javascript db.movies.stats( { scale : 1024 } ) ``` **Output:** ```javascript { 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: ```javascript db.movies.stats( { indexDetails : true } ) ``` **Output:** ```javascript { 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`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-data-collStats.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()`.](https://www.mongodb.com/docs/manual/reference/method/db.collection.getindexes.md#mongodb-method-db.collection.getIndexes) Given the following index: ```javascript { "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. ```javascript 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. ```javascript db.movies.stats( { 'indexDetails' : true, 'indexDetailsName' : 'cast_text_fullplot_text_genres_text_title_text' } ) ``` Both operations return the same output: ```javascript { 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.](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) **See also:** [`$collStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#mongodb-pipeline-pipe.-collStats)