> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, nodejs
-->

# $indexStats (aggregation stage)

## Definition

Returns statistics regarding the use of each index for the collection. If running with [access control](https://www.mongodb.com/docs/manual/core/authorization.md#std-label-authorization), authenticate as a user with at least the [`clusterMonitor`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterMonitor) role.

The [`$indexStats`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#mongodb-pipeline-pipe.-indexStats) stage takes an empty document and has the following syntax:

```javascript
{ $indexStats: { } }
```

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

| Output Field | Description |
| --- | --- |
| `name` | Index name. |
| [key](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-key) | Index key specification. See also: [spec.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-spec) |
| [host](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-host) | The hostname and port of the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) process. |
| [accesses](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-accesses) | Index usage metrics for the associated [host](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-host), including: `ops`: the number of user operations that used the index. This value excludes internal operations, such as deletion by [TTL indexes](https://www.mongodb.com/docs/manual/core/index-ttl.md#std-label-index-feature-ttl) 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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#mongodb-pipeline-pipe.-indexStats) on each node in the cluster. |
| [shard](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-shard) | The name of the shard associated with the [host](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-host) Only available for a sharded cluster. |
| [spec](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-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](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-building) | Indicates if the index is currently being built. Only available if `true`. |

## Behavior

### Accesses Field

The statistics reported by the [accesses](https://www.mongodb.com/docs/manual/reference/operator/aggregation/indexstats.md#std-label-indexStats-output-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](https://www.mongodb.com/docs/manual/core/index-ttl.md#std-label-index-feature-ttl)

- 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.](https://www.mongodb.com/docs/manual/core/transactions.md)

### Index Statistics Reset Considerations

- Statistics for an index reset on [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) restart or index drop and recreation.

- Modification of an existing index (see [`collMod`](https://www.mongodb.com/docs/manual/reference/command/collmod.md#mongodb-collflag-index) command) resets the statistics for that index.

## Examples

### MongoDB Shell

For example, a collection `orders` contains the following documents:

```javascript
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:

```javascript
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:

```javascript
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:

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

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

```javascript
[
   {
      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' }
      }
   }
]
```