Skip to content

Commit c07bf2a

Browse files
author
Sam Kleinman
committed
DOCS-1184 index stat reorganization pre-publication
1 parent 8f19ac5 commit c07bf2a

File tree

4 files changed

+339
-343
lines changed

4 files changed

+339
-343
lines changed

‎source/core/indexes.txt

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -677,7 +677,7 @@ construction:
677677
severe impact on the performance of the database.
678678

679679
Make sure that your application checks for the indexes at start up
680-
using the :method:`getIndexes() <db.collection.getIndexes()>` method
680+
using the :method:`~db.collection.getIndexes()` method
681681
or the :api:`equivalent method for your driver <>` and terminates if
682682
the proper indexes do not exist. Always build indexes in production
683683
instances using separate application code, during designated
@@ -929,7 +929,7 @@ Limitations
929929
each clause of an :operator:`$or` query executes in parallel, and
930930
can each use a different index.
931931

932-
- For queries that use the :method:`sort() <cursor.sort()>` method and
932+
- For queries that use the :method:`~cursor.sort()` method and
933933
use the :operator:`$or` operator, the query **cannot** use the
934934
indexes on the :operator:`$or` fields.
935935

@@ -963,13 +963,11 @@ operations are worth the insertion penalty. However, in some cases:
963963
.. todo:: How do you determine if the above is the case?
964964
Empirically.
965965

966-
- If you have many indexes on a collection with a high insert throughput
967-
and a number of related indexes, you may find better overall
966+
- If you have many related indexes on a collection that receives a
967+
high volume of write operations, you may find better overall
968968
performance with a smaller number of indexes, even if some queries
969969
are less optimally supported by an index.
970970

971-
.. todo:: The above is unclear. -bg
972-
973971
- If your indexes and queries are not sufficiently :ref:`selective
974972
<index-selectivity>`, the speed improvements for query operations
975973
may not offset the costs of maintaining an index. For more

‎source/reference.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,6 @@ Status and Reporting
4444
reference/database-profiler
4545
reference/explain
4646
reference/exit-codes
47-
reference/index-stats
4847

4948
Internal Metadata
5049
-----------------

‎source/reference/command/indexStats.txt

Lines changed: 335 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@ indexStats
44

55
.. default-domain:: mongodb
66

7+
.. contents::
8+
:backlinks: none
9+
:local:
10+
11+
Definition
12+
----------
13+
714
.. dbcommand:: indexStats
815

916
The :dbcommand:`indexStats` command aggregates statistics
@@ -20,10 +27,334 @@ indexStats
2027

2128
db.runCommand( { indexStats: "<collection>", index: "<index name>" } )
2229

23-
For more information on the command's limits and output, see the following:
30+
``indexStats`` Output
31+
---------------------
32+
33+
The :method:`db.collection.indexStats()` method and equivalent
34+
:dbcommand:`indexStats` command aggregate statistics for the B-tree data
35+
structure that stores data for a MongoDB index. The commands aggregate
36+
statistics firstly for the entire B-tree and secondly for each
37+
individual level of the B-tree. The output displays the following
38+
values.
39+
40+
.. data:: indexStats.index
41+
42+
The :ref:`index name <index-names>`.
43+
44+
.. data:: indexStats.version
45+
46+
The index version. For more information on index version numbers, see
47+
the ``v`` option in :method:`db.collection.ensureIndex()`.
48+
49+
.. data:: indexStats.isIdIndex
50+
51+
If ``true``, the index is the default ``_id`` index for the collection.
52+
53+
.. data:: indexStats.keyPattern
54+
55+
The indexed keys.
56+
57+
.. data:: indexStats.storageNs
58+
59+
The namespace of the index's underlying storage.
60+
61+
.. data:: indexStats.bucketBodyBytes
62+
63+
The fixed size, in bytes, of a B-tree bucket in the index, not
64+
including the record header. All indexes for a given version have the
65+
same value for this field. MongoDB allocates fixed size buckets on disk.
66+
67+
.. data:: indexStats.depth
68+
69+
The number of levels in the B-tree, not including the root level.
70+
71+
.. data:: indexStats.overall
72+
73+
This section of the output displays statistics for the entire B-tree.
74+
75+
.. data:: indexStats.overall.numBuckets
76+
77+
The number of buckets in the entire B-tree, including all levels.
78+
79+
.. data:: indexStats.overall.keyCount
80+
81+
Statistics about the number of keys in a bucket, evaluated on a
82+
per-bucket level.
83+
84+
.. data:: indexStats.overall.usedKeyCount
85+
86+
Statistics about the number of used keys in a bucket, evaluated on
87+
a per-bucket level. Used keys are keys not marked as deleted.
88+
89+
.. data:: indexStats.overall.bsonRatio
90+
91+
Statistics about the percentage of the bucket body that is
92+
occupied by the key objects themselves, excluding associated
93+
metadata.
94+
95+
For example, if you have the document ``{ name: "Bob Smith" }``
96+
and an index on ``{ name: 1 }``, the key object is the string
97+
``Bob Smith``.
98+
99+
.. data:: indexStats.overall.keyNodeRatio
100+
101+
Statistics about the percentage of the bucket body that is
102+
occupied by the key node objects (the metadata and links
103+
pertaining to the keys). This does not include the key itself. In
104+
the current implementation, a key node's objects consist of: the
105+
pointer to the key data (in the same bucket), the pointer to the
106+
record the key is for, and the pointer to a child bucket.
107+
108+
.. data:: indexStats.overall.fillRatio
109+
110+
The sum of the :data:`bsonRatio <indexStats.overall.bsonRatio>`
111+
and the :data:`keyNodeRatio <indexStats.overall.keyNodeRatio>`.
112+
This shows how full the buckets are. This will be much higher for
113+
indexes with sequential inserts.
114+
115+
.. data:: indexStats.perLevel
116+
117+
This section of the output displays statistics for each level of the
118+
B-tree separately, starting with the root level. This section
119+
displays a different document for each B-tree level.
120+
121+
.. data:: indexStats.perLevel.numBuckets
122+
123+
The number of buckets at this level of the B-tree.
124+
125+
.. data:: indexStats.perLevel.keyCount
126+
127+
Statistics about the number of keys in a bucket, evaluated on a
128+
per-bucket level.
129+
130+
.. data:: indexStats.perLevel.usedKeyCount
131+
132+
Statistics about the number of used keys in a bucket, evaluated on
133+
a per-bucket level. Used keys are keys not marked as deleted.
134+
135+
.. data:: indexStats.perLevel.bsonRatio
136+
137+
Statistics about the percentage of the bucket body that is
138+
occupied by the key objects themselves, excluding associated
139+
metadata.
140+
141+
.. data:: indexStats.perLevel.keyNodeRatio
142+
143+
Statistics about the percentage of the bucket body that is
144+
occupied by the key node objects (the metadata and links
145+
pertaining to the keys).
146+
147+
.. data:: indexStats.perLevel.fillRatio
148+
149+
The sum of the :data:`bsonRatio <indexStats.perLevel.bsonRatio>`
150+
and the :data:`keyNodeRatio <indexStats.perLevel.keyNodeRatio>`.
151+
This shows how full the buckets are. This will be much higher in
152+
the following cases:
153+
154+
- For indexes with sequential inserts, such as the ``_id`` index
155+
when using ObjectId keys.
156+
157+
- For indexes that were recently built in the foreground with
158+
existing data.
159+
160+
- If you recently ran :dbcommand:`compact` or :option:`--repair
161+
<mongod --repair>`.
162+
163+
.. _example-index-stats-output:
164+
165+
Example Output for Index Stats
166+
------------------------------
167+
168+
The following is an example of :method:`db.collection.indexStats()` and
169+
:dbcommand:`indexStats` output.
170+
171+
.. code-block:: javascript
172+
173+
{
174+
"index" : "type_1_traits_1",
175+
"version" : 1,
176+
"isIdIndex" : false,
177+
"keyPattern" : {
178+
"type" : 1,
179+
"traits" : 1
180+
},
181+
"storageNs" : "test.animals.$type_1_traits_1",
182+
"bucketBodyBytes" : 8154,
183+
"depth" : 2,
184+
"overall" : {
185+
"numBuckets" : 45513,
186+
"keyCount" : {
187+
"count" : NumberLong(45513),
188+
"mean" : 253.89602970579836,
189+
"stddev" : 21.784799875240708,
190+
"min" : 52,
191+
"max" : 290,
192+
"quantiles" : {
193+
"0.01" : 201.99785091648775,
194+
// ...
195+
"0.99" : 289.9999655156967
196+
}
197+
},
198+
"usedKeyCount" : {
199+
"count" : NumberLong(45513),
200+
// ...
201+
"quantiles" : {
202+
"0.01" : 201.99785091648775,
203+
// ...
204+
"0.99" : 289.9999655156967
205+
}
206+
},
207+
"bsonRatio" : {
208+
"count" : NumberLong(45513),
209+
// ...
210+
"quantiles" : {
211+
"0.01" : 0.4267797891997124,
212+
// ...
213+
"0.99" : 0.5945548174629648
214+
}
215+
},
216+
"keyNodeRatio" : {
217+
"count" : NumberLong(45513),
218+
// ...
219+
"quantiles" : {
220+
"0.01" : 0.3963656628236211,
221+
// ...
222+
"0.99" : 0.5690457993930765
223+
}
224+
},
225+
"fillRatio" : {
226+
"count" : NumberLong(45513),
227+
// ...
228+
"quantiles" : {
229+
"0.01" : 0.9909134214926929,
230+
// ...
231+
"0.99" : 0.9960755457453732
232+
}
233+
}
234+
},
235+
"perLevel" : [
236+
{
237+
"numBuckets" : 1,
238+
"keyCount" : {
239+
"count" : NumberLong(1),
240+
"mean" : 180,
241+
"stddev" : 0,
242+
"min" : 180,
243+
"max" : 180
244+
},
245+
"usedKeyCount" : {
246+
"count" : NumberLong(1),
247+
// ...
248+
"max" : 180
249+
},
250+
"bsonRatio" : {
251+
"count" : NumberLong(1),
252+
// ...
253+
"max" : 0.3619082658817758
254+
},
255+
"keyNodeRatio" : {
256+
"count" : NumberLong(1),
257+
// ...
258+
"max" : 0.35320088300220753
259+
},
260+
"fillRatio" : {
261+
"count" : NumberLong(1),
262+
// ...
263+
"max" : 0.7151091488839834
264+
}
265+
},
266+
{
267+
"numBuckets" : 180,
268+
"keyCount" : {
269+
"count" : NumberLong(180),
270+
"mean" : 250.84444444444443,
271+
"stddev" : 26.30057503009355,
272+
"min" : 52,
273+
"max" : 290
274+
},
275+
"usedKeyCount" : {
276+
"count" : NumberLong(180),
277+
// ...
278+
"max" : 290
279+
},
280+
"bsonRatio" : {
281+
"count" : NumberLong(180),
282+
// ...
283+
"max" : 0.5945548197203826
284+
},
285+
"keyNodeRatio" : {
286+
"count" : NumberLong(180),
287+
// ...
288+
"max" : 0.5690458670591121
289+
},
290+
"fillRatio" : {
291+
"count" : NumberLong(180),
292+
// ...
293+
"max" : 0.9963208241353937
294+
}
295+
},
296+
{
297+
"numBuckets" : 45332,
298+
"keyCount" : {
299+
"count" : NumberLong(45332),
300+
"mean" : 253.90977675813994,
301+
"stddev" : 21.761620836279018,
302+
"min" : 167,
303+
"max" : 290,
304+
"quantiles" : {
305+
"0.01" : 202.0000012563603,
306+
// ...
307+
"0.99" : 289.99996486571894
308+
}
309+
},
310+
"usedKeyCount" : {
311+
"count" : NumberLong(45332),
312+
// ...
313+
"quantiles" : {
314+
"0.01" : 202.0000012563603,
315+
// ...
316+
"0.99" : 289.99996486571894
317+
}
318+
},
319+
"bsonRatio" : {
320+
"count" : NumberLong(45332),
321+
// ...
322+
"quantiles" : {
323+
"0.01" : 0.42678446958950583,
324+
// ...
325+
"0.99" : 0.5945548175411283
326+
}
327+
},
328+
"keyNodeRatio" : {
329+
"count" : NumberLong(45332),
330+
// ...
331+
"quantiles" : {
332+
"0.01" : 0.39636988227885306,
333+
// ...
334+
"0.99" : 0.5690457981176729
335+
}
336+
},
337+
"fillRatio" : {
338+
"count" : NumberLong(45332),
339+
// ...
340+
"quantiles" : {
341+
"0.01" : 0.9909246995605362,
342+
// ...
343+
"0.99" : 0.996075546919481
344+
}
345+
}
346+
}
347+
],
348+
"ok" : 1
349+
}
350+
351+
Additional Resources
352+
--------------------
353+
354+
For more information on the command's limits and output, see the following:
24355

25-
- The equivalent :method:`db.collection.indexStats()` method
356+
- The equivalent :method:`db.collection.indexStats()` method,
26357

27-
- :doc:`/reference/index-stats`
358+
- :doc:`/reference/index-stats`, and
28359

29-
- `https://github.com/10gen-labs/storage-viz#readme <https://github.com/10gen-labs/storage-viz#readme>`_.
360+
- `https://github.com/10gen-labs/storage-viz#readme <https://github.com/10gen-labs/storage-viz#readme>`_.

0 commit comments

Comments
 (0)