/ /

Database Commands

Diagnostic Commands

Docs Home

MongoDB Manual

Reference

Database Commands

Diagnostic Commands

dbStats

This version of the documentation is archived and no longer supported. View the current documentation to learn how to upgrade your version of MongoDB.

Definition

dbStats

The dbStats command returns storage statistics for a given database. The command has the following syntax:

db.runCommand( {
   dbStats: 1,
   scale: <number>       //Optional
} )

The dbStats command takes the following fields:

Parameter	Description
`dbStats`	1
scale	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.

Parameter

Description

dbStats

scale

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.

In the mongo shell, the db.stats() function provides a wrapper around dbStats.

Behavior

The time required to run the command depends on the total size of the database. Because the command must touch all data files, the command may take several seconds to run.

Accuracy after Unexpected Shutdown

After an unclean shutdown of a mongod using the Wired Tiger storage engine, count and size statistics reported by dbStats 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

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

In previous versions, the operations also run when the member is in STARTUP2. The operations wait until the member transitioned to RECOVERING.

Output

dbStats.db: Contains the name of the database.

dbStats.collections: Contains a count of the number of collections in that database.

dbStats.views: Contains a count of the number of views in that database.

dbStats.objects: Contains a count of the number of objects (i.e. documents) in the database across all collections.

dbStats.avgObjSize: The average size of each document in bytes. This is the dataSize divided by the number of documents. The scale argument does not affect the avgObjSize value.

dbStats.dataSize

The total size of the uncompressed data held in this database. The dataSize decreases when you remove documents.

For databases using the WiredTiger storage engine, dataSize may be larger than storageSize if compression is enabled. The dataSize decreases when documents shrink.

dbStats.storageSize

The total amount of space allocated to collections in this database for document storage. The storageSize does not decrease as you remove or shrink documents. This value may be smaller than dataSize for databases using the WiredTiger storage engine with compression enabled.

storageSize does not include the index size. See indexSize for index sizing.

dbStats.indexes: Contains a count of the total number of indexes across all collections in the database.

dbStats.indexSize: The total size of all indexes created on this database.

dbStats.totalSize: The sum of the storageSize and indexSize.
New in version 4.4.

dbStats.scaleFactor

The scale value used by the command.

If you specified 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.

New in version 4.2.

dbStats.fsUsedSize: New in version 3.6.
Total size of all disk space in use on the filesystem where MongoDB stores data.
Tip
--dbpath

dbStats.fsTotalSize: New in version 3.6.
Total size of all disk capacity on the filesystem where MongoDB stores data.

Back

dbHash

driverOIDTest

Definition

Behavior

Accuracy after Unexpected Shutdown

Replica Set Member State Restriction

Output

Tip