========================= $indexStats (aggregation) ========================= .. default-domain:: mongodb .. contents:: On this page :local: :backlinks: none :depth: 1 :class: singlecol Definition ---------- .. pipeline:: $indexStats .. versionadded:: 3.2 Returns statistics regarding the use of each index for the collection. If running with :doc:`access control `, the user must have privileges that include :authaction:`indexStats` action. The :pipeline:`$indexStats` stage takes an empty document and has the following syntax: .. code-block:: javascript { $indexStats: { } } The return document includes the following fields: .. list-table:: :header-rows: 1 :widths: 30 70 * - Output Field - Description * - ``name`` - Index name. * - ``key`` - Index key specification. * - ``host`` - The hostname and port of the :binary:`~bin.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. Statistics for an index will be reset on :binary:`~bin.mongod` restart or index drop and recreation. .. include:: /includes/note-indexstats-behavior.rst Behavior -------- The statistics reported by the ``accesses`` field only includes index access driven by user requests. It does not include internal operations like deletion via :doc:`/core/index-ttl` or chunk split and migration operations. ``$indexStats`` must be the first stage in an aggregation pipeline. ``$indexStats`` is not allowed in :doc:`transactions `. Example ------- For example, a collection ``orders`` contains the following documents: .. code-block:: javascript { "_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: .. code-block:: javascript db.orders.createIndex( { item: 1, quantity: 1 } ) db.orders.createIndex( { type: 1, item: 1 } ) Run some queries against the collection: .. code-block:: javascript 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: .. code-block:: javascript db.orders.aggregate( [ { $indexStats: { } } ] ) The operation returns a document that contains usage statistics for each index: .. code-block:: json { "name" : "item_1_quantity_1", "key" : { "item" : 1, "quantity" : 1 }, "host" : "examplehost.local:27017", "accesses" : { "ops" : NumberLong(1), "since" : ISODate("2015-10-02T14:31:53.685Z") } } { "name" : "_id_", "key" : { "_id" : 1 }, "host" : "examplehost.local:27017", "accesses" : { "ops" : NumberLong(0), "since" : ISODate("2015-10-02T14:31:32.479Z") } } { "name" : "type_1_item_1", "key" : { "type" : 1, "item" : 1 }, "host" : "examplehost.local:27017", "accesses" : { "ops" : NumberLong(1), "since" : ISODate("2015-10-02T14:31:58.321Z") } }