Docs Home → Develop Applications → MongoDB Manual

$indexStats (aggregation)

On this page

Definition

Behavior
Example

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

Definition

$indexStats

New in version 3.2.

Returns statistics regarding the use of each index for the collection. If running with access control, the user must have privileges that include indexStats action.

The $indexStats stage takes an empty document and has the following syntax:

{ $indexStats: { } }

For each index, the return document includes the following fields:

Output Field	Description
`name`	Index name.
key	Index key specification. See also: spec.
host	The hostname and port of the `mongod` process.
accesses	Statistics on the index use: `ops` is the number of operations that used the index. `since` is the time from which MongoDB gathered the statistics.
shard	The name of the shard associated with the host Only available for a sharded cluster. New in version 4.2.4.
spec	The full specfication document for the index, which includes the index key specification document. The index option `hidden`, available starting in MongoDB 4.4, is only included if the value is `true`. New in version 4.2.4.
building	Indicates if the index is currently being built. Only available if `true`. New in version 4.2.4.

Statistics for an index will be reset on mongod restart or index drop and recreation.

Note

Prior to version 3.2.3, the ops field value did not include $match or mapReduce operations that use indexes.

Behavior

Accesses Field

The statistics reported by the accesses field only includes index access driven by user requests. It does not include internal operations like deletion via TTL Indexes or chunk split and migration operations.

Restrictions

$indexStats must be the first stage in an aggregation pipeline.
$indexStats is not allowed in transactions.

Index Modifications Resets Statistics

Modification of an existing index (see collMod command) resets the statistics for that index.

Example

For example, a collection orders contains the following documents:

{ "_id" : 1, "item" : "abc", "price" : 12, "quantity" : 2, "type": "apparel" }
{ "_id" : 2, "item" : "jkl", "price" : 20, "quantity" : 1, "type": "electronics" }
{ "_id" : 3, "item" : "abc", "price" : 10, "quantity" : 5, "type": "apparel" }

Create the following two indexes on the collection:

db.orders.createIndex( { item: 1, quantity: 1 } )
db.orders.createIndex( { type: 1, item: 1 } )

Run some queries against the collection:

db.orders.find( { type: "apparel"} )
db.orders.find( { item: "abc" } ).sort( { quantity: 1 } )

To view statistics on the index use on the orders collection, run the following aggregation operation:

db.orders.aggregate( [ { $indexStats: { } } ] )

The operation returns a document that contains usage statistics for each index:

{
   "name" : "item_1_quantity_1",
   "key" : { "item" : 1, "quantity" : 1 },
   "host" : "examplehost.local:27018",
   "accesses" : {
      "ops" : NumberLong(1),
      "since" : ISODate("2020-02-10T21:11:23.059Z")
   },
   "shard" : "shardA",      // Available starting in MongoDB 4.2.4 if run on sharded cluster
   "spec" : {               // Available starting in MongoDB 4.2.4
      "v" : 2,
      "key" : { "item" : 1, "quantity" : 1 },
      "name" : "item_1_quantity_1"
   }
}
{
   "name" : "item_1_price_1",
   "key" : { "item" : 1, "price" : 1 },
   "host" : "examplehost.local:27018",
   "accesses" : {
      "ops" : NumberLong(1),
      "since" : ISODate("2020-02-10T21:11:23.233Z")
   },
   "shard" : "shardA",      // Available starting in MongoDB 4.2.4 if run on sharded cluster
   "spec" : {               // Available starting in MongoDB 4.2.4
      "v" : 2,
      "key" : { "item" : 1, "price" : 1 },
      "name" : "item_1_price_1"
   }
}
{
   "name" : "item_1",
   "key" : { "item" : 1 },
   "host" : "examplehost.local:27018",
   "accesses" : {
      "ops" : NumberLong(0),
      "since" : ISODate("2020-02-10T21:11:22.947Z")
   },
   "shard" : "shardA",      // Available starting in MongoDB 4.2.4 if run on sharded cluster
   "spec" : {               // Available starting in MongoDB 4.2.4
      "v" : 2,
      "key" : { "item" : 1 },
      "name" : "item_1"
   }
}
{
   "name" : "_id_",
   "key" : { "_id" : 1 },
   "host" : "examplehost.local:27018",
   "accesses" : {
      "ops" : NumberLong(0),
      "since" : ISODate("2020-02-10T21:11:18.298Z")
   },
   "shard" : "shardA",      // Available starting in MongoDB 4.2.4 if run on sharded cluster
   "spec" : {               // Available starting in MongoDB 4.2.4
      "v" : 2,
      "key" : { "_id" : 1 },
      "name" : "_id_"
   }
}

← $group (aggregation)$limit (aggregation) →