From 9b98eb0860efef31c6758a7a5d06788a99472346 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Thu, 4 Apr 2013 19:27:22 -0400 Subject: [PATCH] DOCS-1184 indexStats() command --- source/core/indexes.txt | 33 ++ source/reference.txt | 1 + source/reference/command/indexStats.txt | 29 ++ source/reference/index-stats.txt | 332 ++++++++++++++++++ .../method/db.collection.indexStats.txt | 46 +++ source/reference/user-privileges.txt | 2 +- 6 files changed, 442 insertions(+), 1 deletion(-) create mode 100644 source/reference/command/indexStats.txt create mode 100644 source/reference/index-stats.txt create mode 100644 source/reference/method/db.collection.indexStats.txt diff --git a/source/core/indexes.txt b/source/core/indexes.txt index fbab9131932..7938b9c57c7 100644 --- a/source/core/indexes.txt +++ b/source/core/indexes.txt @@ -567,6 +567,39 @@ the ``a`` field. .. [#hash-size] The hash stored in the ``hashed`` index is 64 bits of the 128 bit ``md5`` hash. +.. index:: index; name +.. _index-names: + +Index Names +----------- + +The default name for an index is the concatenation of the indexed keys +and each key's direction in the index (1 or -1). + +.. example:: Issue the following command to create an index on ``item`` + and ``quantity``: + + .. code-block:: javascript + + db.products.ensureIndex( { item: 1, quantity: -1 } ) + + The resulting index is named: ``item_1_quantity_-1``. + +Optionally. you can specify a name for an index instead of using the +default name. + +.. example:: Issue the following command to create an index on ``item`` + and ``quantity`` and specify ``inventory`` as the index name: + + .. code-block:: javascript + + db.products.ensureIndex( { item: 1, quantity: -1 } , {name: "inventory"} ) + + The resulting index is named: ``inventory``. + +To view the name of an index, use the :method:`getIndexes() +` method. + .. index:: index; options .. _index-creation-operations: .. _index-operations: diff --git a/source/reference.txt b/source/reference.txt index 114e902f5b5..7821ab77f77 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -44,6 +44,7 @@ Status and Reporting reference/database-profiler reference/explain reference/exit-codes + reference/index-stats Internal Metadata ----------------- diff --git a/source/reference/command/indexStats.txt b/source/reference/command/indexStats.txt new file mode 100644 index 00000000000..204093931ac --- /dev/null +++ b/source/reference/command/indexStats.txt @@ -0,0 +1,29 @@ +========== +indexStats +========== + +.. default-domain:: mongodb + +.. dbcommand:: indexStats + + The :dbcommand:`indexStats` command aggregates statistics + for the B-tree data structure that stores data for a MongoDB index. + + .. warning:: This command is not intended for production deployments. + + The command can be run *only* on a :program:`mongod` instance that uses + the ``--enableExperimentalIndexStatsCmd`` option. + + To aggregate statistics, issue the command like so: + + .. code-block:: javascript + + db.runCommand( { indexStats: "", index: "" } ) + + For more information on the command's limits and output, see the following: + + - The equivalent :method:`db.collection.indexStats()` method + + - :doc:`/reference/index-stats` + + - `https://github.com/10gen-labs/storage-viz#readme `_. diff --git a/source/reference/index-stats.txt b/source/reference/index-stats.txt new file mode 100644 index 00000000000..a6cd682e13d --- /dev/null +++ b/source/reference/index-stats.txt @@ -0,0 +1,332 @@ +================== +Index Stats Output +================== + +.. default-domain:: mongodb + +This document describes the output of the +:method:`db.collection.indexStats()` method and the equivalent +:dbcommand:`indexStats` command. This document includes an example of +the output. + +indexStats Output +----------------- + +The :method:`db.collection.indexStats()` method and equivalent +:dbcommand:`indexStats` command aggregate statistics for the B-tree data +structure that stores data for a MongoDB index. The commands aggregate +statistics firstly for the entire B-tree and secondly for each +individual level of the B-tree. The output displays the following +values. + +.. data:: indexStats.index + + The :ref:`index name `. + +.. data:: indexStats.version + + The index version. For more information on index version numbers, see + the ``v`` option in :method:`db.collection.ensureIndex()`. + +.. data:: indexStats.isIdIndex + + If ``true``, the index is the default ``_id`` index for the collection. + +.. data:: indexStats.keyPattern + + The indexed keys. + +.. data:: indexStats.storageNs + + The namespace of the index's underlying storage. + +.. data:: indexStats.bucketBodyBytes + + The fixed size, in bytes, of a B-tree bucket in the index, not + including the record header. All indexes for a given version have the + same value for this field. MongoDB allocates fixed size buckets on disk. + +.. data:: indexStats.depth + + The number of levels in the B-tree, not including the root level. + +.. data:: indexStats.overall + + This section of the output displays statistics for the entire B-tree. + + .. data:: indexStats.overall.numBuckets + + The number of buckets in the entire B-tree, including all levels. + + .. data:: indexStats.overall.keyCount + + Statistics about the number of keys in a bucket, evaluated on a + per-bucket level. + + .. data:: indexStats.overall.usedKeyCount + + Statistics about the number of used keys in a bucket, evaluated on + a per-bucket level. Used keys are keys not marked as deleted. + + .. data:: indexStats.overall.bsonRatio + + Statistics about the percentage of the bucket body that is + occupied by the key objects themselves, excluding associated + metadata. + + For example, if you have the document ``{ name: "Bob Smith" }`` + and an index on ``{ name: 1 }``, the key object is the string + ``Bob Smith``. + + .. data:: indexStats.overall.keyNodeRatio + + Statistics about the percentage of the bucket body that is + occupied by the key node objects (the metadata and links + pertaining to the keys). This does not include the key itself. In + the current implementation, a key node's objects consist of: the + pointer to the key data (in the same bucket), the pointer to the + record the key is for, and the pointer to a child bucket. + + .. data:: indexStats.overall.fillRatio + + The sum of the :data:`bsonRatio ` + and the :data:`keyNodeRatio `. + This shows how full the buckets are. This will be much higher for + indexes with sequential inserts. + +.. data:: indexStats.perLevel + + This section of the output displays statistics for each level of the + B-tree separately, starting with the root level. This section + displays a different document for each B-tree level. + + .. data:: indexStats.perLevel.numBuckets + + The number of buckets at this level of the B-tree. + + .. data:: indexStats.perLevel.keyCount + + Statistics about the number of keys in a bucket, evaluated on a + per-bucket level. + + .. data:: indexStats.perLevel.usedKeyCount + + Statistics about the number of used keys in a bucket, evaluated on + a per-bucket level. Used keys are keys not marked as deleted. + + .. data:: indexStats.perLevel.bsonRatio + + Statistics about the percentage of the bucket body that is + occupied by the key objects themselves, excluding associated + metadata. + + .. data:: indexStats.perLevel.keyNodeRatio + + Statistics about the percentage of the bucket body that is + occupied by the key node objects (the metadata and links + pertaining to the keys). + + .. data:: indexStats.perLevel.fillRatio + + The sum of the :data:`bsonRatio ` + and the :data:`keyNodeRatio `. + This shows how full the buckets are. This will be much higher in + the following cases: + + - For indexes with sequential inserts, such as the ``_id`` index + when using ObjectId keys. + + - For indexes that were recently built in the foreground with + existing data. + + - If you recently ran :dbcommand:`compact` or :option:`--repair + `. + +.. _example-index-stats-output: + +Example Output for Index Stats +------------------------------ + +The following is an example of :method:`db.collection.indexStats()` and +:dbcommand:`indexStats` output. + +.. code-block:: javascript + + { + "index" : "type_1_traits_1", + "version" : 1, + "isIdIndex" : false, + "keyPattern" : { + "type" : 1, + "traits" : 1 + }, + "storageNs" : "test.animals.$type_1_traits_1", + "bucketBodyBytes" : 8154, + "depth" : 2, + "overall" : { + "numBuckets" : 45513, + "keyCount" : { + "count" : NumberLong(45513), + "mean" : 253.89602970579836, + "stddev" : 21.784799875240708, + "min" : 52, + "max" : 290, + "quantiles" : { + "0.01" : 201.99785091648775, + // ... + "0.99" : 289.9999655156967 + } + }, + "usedKeyCount" : { + "count" : NumberLong(45513), + // ... + "quantiles" : { + "0.01" : 201.99785091648775, + // ... + "0.99" : 289.9999655156967 + } + }, + "bsonRatio" : { + "count" : NumberLong(45513), + // ... + "quantiles" : { + "0.01" : 0.4267797891997124, + // ... + "0.99" : 0.5945548174629648 + } + }, + "keyNodeRatio" : { + "count" : NumberLong(45513), + // ... + "quantiles" : { + "0.01" : 0.3963656628236211, + // ... + "0.99" : 0.5690457993930765 + } + }, + "fillRatio" : { + "count" : NumberLong(45513), + // ... + "quantiles" : { + "0.01" : 0.9909134214926929, + // ... + "0.99" : 0.9960755457453732 + } + } + }, + "perLevel" : [ + { + "numBuckets" : 1, + "keyCount" : { + "count" : NumberLong(1), + "mean" : 180, + "stddev" : 0, + "min" : 180, + "max" : 180 + }, + "usedKeyCount" : { + "count" : NumberLong(1), + // ... + "max" : 180 + }, + "bsonRatio" : { + "count" : NumberLong(1), + // ... + "max" : 0.3619082658817758 + }, + "keyNodeRatio" : { + "count" : NumberLong(1), + // ... + "max" : 0.35320088300220753 + }, + "fillRatio" : { + "count" : NumberLong(1), + // ... + "max" : 0.7151091488839834 + } + }, + { + "numBuckets" : 180, + "keyCount" : { + "count" : NumberLong(180), + "mean" : 250.84444444444443, + "stddev" : 26.30057503009355, + "min" : 52, + "max" : 290 + }, + "usedKeyCount" : { + "count" : NumberLong(180), + // ... + "max" : 290 + }, + "bsonRatio" : { + "count" : NumberLong(180), + // ... + "max" : 0.5945548197203826 + }, + "keyNodeRatio" : { + "count" : NumberLong(180), + // ... + "max" : 0.5690458670591121 + }, + "fillRatio" : { + "count" : NumberLong(180), + // ... + "max" : 0.9963208241353937 + } + }, + { + "numBuckets" : 45332, + "keyCount" : { + "count" : NumberLong(45332), + "mean" : 253.90977675813994, + "stddev" : 21.761620836279018, + "min" : 167, + "max" : 290, + "quantiles" : { + "0.01" : 202.0000012563603, + // ... + "0.99" : 289.99996486571894 + } + }, + "usedKeyCount" : { + "count" : NumberLong(45332), + // ... + "quantiles" : { + "0.01" : 202.0000012563603, + // ... + "0.99" : 289.99996486571894 + } + }, + "bsonRatio" : { + "count" : NumberLong(45332), + // ... + "quantiles" : { + "0.01" : 0.42678446958950583, + // ... + "0.99" : 0.5945548175411283 + } + }, + "keyNodeRatio" : { + "count" : NumberLong(45332), + // ... + "quantiles" : { + "0.01" : 0.39636988227885306, + // ... + "0.99" : 0.5690457981176729 + } + }, + "fillRatio" : { + "count" : NumberLong(45332), + // ... + "quantiles" : { + "0.01" : 0.9909246995605362, + // ... + "0.99" : 0.996075546919481 + } + } + } + ], + "ok" : 1 + } + \ No newline at end of file diff --git a/source/reference/method/db.collection.indexStats.txt b/source/reference/method/db.collection.indexStats.txt new file mode 100644 index 00000000000..f84e1369bc3 --- /dev/null +++ b/source/reference/method/db.collection.indexStats.txt @@ -0,0 +1,46 @@ +========================== +db.collection.indexStats() +========================== + +.. default-domain:: mongodb + +.. method:: db.collection.indexStats(index) + + The :method:`db.collection.indexStats()` method is a thin wrapper + around the :dbcommand:`indexStats` command. The method and command + aggregate statistics for the B-tree data structure that stores data + for a MongoDB index. + + The command can be run only on a :program:`mongod` instance that uses + the ``--enableExperimentalIndexStatsCmd`` option. + + .. warning:: The :method:`db.collection.indexStats()` method is not intended for + production deployments. + + The :method:`db.collection.indexStats()` method takes the following + parameter: + + :param string collection: + + Specifies the index. + + .. example:: + + .. code-block:: javascript + + db..indexStats( { index: "" } ) + + The method takes a read lock and pages into memory all the extents, or + B-tree buckets, encountered. The method might be slow for large indexes + if the underlying extents are not already in physical memory. Do not run + :method:`db.collection.indexStats()` on a :term:`replica set` :term:`primary`. When run + on a :term:`secondary`, the command causes the secondary to fall behind + on replication. + + The method aggregates statistics + for the entire B-tree and for each individual level of the B-tree. + For a description of the command's output, see + :doc:`/reference/index-stats`. + + For more information about running :method:`db.collection.indexStats()`, see + `https://github.com/10gen-labs/storage-viz#readme `_. diff --git a/source/reference/user-privileges.txt b/source/reference/user-privileges.txt index 50594805051..cdb82d3f147 100644 --- a/source/reference/user-privileges.txt +++ b/source/reference/user-privileges.txt @@ -116,6 +116,7 @@ Database Administration Roles - :method:`~db.collection.drop()` - :dbcommand:`dropIndexes` - :method:`db.collection.ensureIndex()` + - :dbcommand:`indexStats` - :dbcommand:`profile` - :dbcommand:`reIndex` - :dbcommand:`renameCollection` (within a single database.) @@ -124,7 +125,6 @@ Database Administration Roles Furthermore only :authrole:`dbAdmin` has the ability to read the :data:`system.profile <.system.profile>` collection. - .. - :dbcommand:`indexStats` (experimental feature.) .. - :dbcommand:`storageDetails` (experimental command.) (not documented.)