Docs Home → Develop Applications → MongoDB Manual
dbStats![](/docs/v5.3/assets/link.svg)
On this page
Definition![](/docs/v5.3/assets/link.svg)
dbStats
The
dbStats
command returns storage statistics for a given database. The command has the following syntax:db.runCommand( { dbStats: 1, scale: <number>, freeStorage: 0 } ) The
dbStats
command takes the following fields:FieldsDescription1Optional. 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 ascale
value of1024
.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 uses1023
as the scale factor.Starting in version 4.2, the output includes the
scaleFactor
used to scale the size values.Optional. To return details on free space allocated to collections, set
freeStorage
to 1.If the instance has a large number of collections or indexes, obtaining free space usage data may cause processing delays. To gather
dbStats
information without free space details, either setfreeStorage
to 0 or do not include the field.In
mongosh
, thedb.stats()
function provides a wrapper arounddbStats
.
Behavior![](/docs/v5.3/assets/link.svg)
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![](/docs/v5.3/assets/link.svg)
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:
Replica Set Member State Restriction![](/docs/v5.3/assets/link.svg)
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![](/docs/v5.3/assets/link.svg)
dbStats.views
Number of views in the database.
dbStats.objects
Number of objects (specifically, documents) in the database across all collections.
dbStats.avgObjSize
Average size of each document in bytes. This is the
dataSize
divided by the number of documents. The scale argument does not affect theavgObjSize
value.
dbStats.dataSize
Total size of the uncompressed data held in the database. The
dataSize
decreases when you remove documents.For databases using the WiredTiger storage engine,
dataSize
may be larger thanstorageSize
if compression is enabled. ThedataSize
decreases when documents shrink.
dbStats.storageSize
Sum of the space allocated to all collections in the database for document storage, including free space.
The
storageSize
does not decrease as you remove or shrink documents. This value may be smaller thandataSize
for databases using the WiredTiger storage engine with compression enabled.storageSize
does not include space allocated to indexes. SeeindexSize
for the total index size.
dbStats.freeStorageSize
Sum of the free space allocated to all collections in the database for document storage. Free database storage space is allocated to the collection but does not contain data.
freeStorageSize
does not include free space allocated to indexes. SeeindexFreeStorageSize
for the total free index size.To include this value in the
dbStats
output, set freeStorage to 1.Updated in version 5.3.0, 5.2.1, and 5.0.6.
dbStats.indexSize
Sum of the space allocated to all indexes in the database, including free index space.
dbStats.indexFreeStorageSize
Sum of the free space allocated to all indexes in the database. Free database storage space is allocated to the index but does not contain data.
indexFreeStorageSize
does not include free space allocated to document storage. SeefreeStorageSize
for the total free document storage size.To include this value in the
dbStats
output, set freeStorage to 1.Updated in version 5.3.0, 5.2.1, and 5.0.6.
dbStats.totalSize
Sum of the space allocated for both documents and indexes in all collections in the database. Includes used and free storage space. This is the sum of
storageSize
andindexSize
.New in version 4.4.
dbStats.totalFreeStorageSize
Sum of the free storage space allocated for both documents and indexes in all collections in the database. This is the sum of
freeStorageSize
andindexFreeStorageSize
.To include this value in the
dbStats
output, set freeStorage to 1.Updated in version 5.3.0, 5.2.1, and 5.0.6.
dbStats.scaleFactor
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 uses1023
as the scale factor.New in version 4.2.
Examples![](/docs/v5.3/assets/link.svg)
The following examples demonstrate dbStats
usage.
Limit Data Returned![](/docs/v5.3/assets/link.svg)
To limit the data returned to a single field, append the field name to
the dbStats
command. This example returns the
indexSize
value:
db.runCommand( { dbStats: 1 } ).indexSize
View Free Space Allocated to Collections![](/docs/v5.3/assets/link.svg)
To view free storage usage, set freeStorage to 1.
db.runCommand( { dbStats: 1, scale: 1024, freeStorage: 1 } )
Example output:
{ db: 'test', collections: 2, views: 0, objects: 1689, avgObjSize: 52.56542332741267, dataSize: 86.7021484375, storageSize: 100, freeStorageSize: 32, indexes: 2, indexSize: 116, indexFreeStorageSize: 36, totalSize: 216, totalFreeStorageSize: 68, scaleFactor: 1024, fsUsedSize: 60155820, fsTotalSize: 61255492, ok: 1, '$clusterTime': { clusterTime: Timestamp({ t: 1646085664, i: 1 }), signature: { hash: Binary(Buffer.from("0000000000000000000000000000000000000000", "hex"), 0), keyId: Long("0") } }, operationTime: Timestamp({ t: 1646085664, i: 1 }) }
The freeStorage field enables the collection and display of the highlighted metrics.
The scale field sets the displayed values to kilobytes.