/ /

$indexStats (aggregation stage)

Definition

$indexStats

Returns statistics regarding the use of each index for the collection. If running with access control, authenticate as a user with at least the clusterMonitor role.

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	Index usage metrics for the associated host, including: `ops`: the number of user operations that used the index. This value excludes internal operations, such as deletion by TTL indexes or chunk split and migration operations. This exclusion also covers index access from replication, such as oplog application and index builds during initial sync. `since`: the time from which MongoDB gathered the statistics WARNING: The `accesses` field reports index usage metrics only for the node where the query runs. For more comprehensive index usage statistics, run `$indexStats` on each node in the cluster.
shard	The name of the shard associated with the host Only available for a sharded cluster.
spec	The full specification document for the index, which includes the index key and index properties. The index option `hidden` is only included if the value is `true`.
building	Indicates if the index is currently being built. Only available if `true`.

Behavior

Accesses Field

The statistics reported by the accesses field only apply to the node where the query is being run and only include index access driven by user requests. The accesses field excludes the following internal operations:

Deletion by TTL indexes
Chunk split and migration operations
Index access from replication, such as oplog application and index builds during initial sync

Restrictions

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

Index Statistics Reset Considerations

Statistics for an index reset on mongod restart or index drop and recreation.
Modification of an existing index (see collMod command) resets the statistics for that index.

Examples

For example, a collection orders contains the following documents:

db.orders.insertMany( [
   { _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 } )
db.orders.createIndex(
   { price: 1 },
   { partialFilterExpression: { type: "apparel" } }
)

Run some queries against the collection:

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

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: 'type_1_item_1',
      key: { type: 1, item: 1 },
      host: 'examplehost.local:27018',
      accesses: { ops: Long("1"), since: ISODate("2024-05-02T15:07:21.420Z") },
      shard: "shardA",
      spec: { v: 2, key: { type: 1, item: 1 }, name: 'type_1_item_1' }
   },
   {
      name: 'item_1_quantity_1',
      key: { item: 1, quantity: 1 },
      host: 'examplehost.local:27018',
      accesses: { ops: Long("1"), since: ISODate("2024-05-02T15:07:21.254Z") },
      shard: "shardA",
      spec: { v: 2, key: { item: 1, quantity: 1 }, name: 'item_1_quantity_1' }
   },
   {
      name: '_id_',
      key: { _id: 1 },
      host: 'examplehost.local:27018',
      accesses: { ops: Long("0"), since: ISODate("2024-05-02T15:07:13.274Z") },
      shard: "shardA",
      spec: { v: 2, key: { _id: 1 }, name: '_id_' }
   },
   {
      name: 'price_1',
      key: { price: 1 },
      host: 'examplehost.local:27018',
      accesses: { ops: Long("0"), since: ISODate("2024-05-02T15:07:54.847Z") },
      shard: "shardA",
      spec: {
         v: 2,
         key: { price: 1 },
         name: 'price_1',
         partialFilterExpression: { type: 'apparel' }
      }
   }
]

To use the MongoDB Node.js driver to add a $indexStats stage to an aggregation pipeline, use the $indexStats operator in a pipeline object.

The following example creates a pipeline stage that returns a document that contains usage statistics for each index on the collection. The example then runs the aggregation pipeline:

const pipeline = [{ $indexStats: {} }];
const cursor = collection.aggregate(pipeline);
return cursor;

Back

$group

$limit