DOCS-5392 : nscanned/keysExamined "end" check update

R2: CR + addtl. feedback

R3: Further Refinement

Author: ravindk89

source/reference/explain-results.txt

@@ -181,8 +181,10 @@ information:
          "inputStage" : {
             "stage" : <STAGE2>,
             ...
-            "nReturned" : 0,
+            "nReturned" : <int>,
             "executionTimeMillisEstimate" : <int>,
+            "keysExamined" : <int>,
+            "docsExamined" : <int>,
             ...
             "inputStage" : {
                ...
@@ -219,9 +221,9 @@ information:
    .. data:: explain.executionStats.totalKeysExamined
 
       Number of index entries scanned.
-      :data:`~explain.executionStats.totalKeysExamined` corresponds to the
-      ``nscanned`` field returned by ``cursor.explain()`` in earlier
-      versions of MongoDB.
+      :data:`~explain.executionStats.totalKeysExamined` corresponds to the 
+      ``nscanned`` field returned by ``cursor.explain()`` in 
+      earlier versions of MongoDB.
 
    .. data:: explain.executionStats.totalDocsExamined
 
@@ -283,6 +285,42 @@ information:
            returns more than the specified limit, the ``LIMIT`` stage
            will report ``isEOF: 1``, but its underlying ``IXSCAN`` stage
            will report ``isEOF: 0``.
+           
+      .. data:: explain.executionStats.executionStages.inputStage.keysExamined
+         
+         For query execution stages that scan an index (e.g. IXSCAN), 
+         ``keysExamined`` is the total number of in-bounds and out-of-bounds 
+         keys that are examined in the process of the index scan. If the 
+         index scan consists of a single contiguous range of keys, only 
+         in-bounds keys need to be examined. If the index bounds consists of 
+         several key ranges, the index scan execution process may examine 
+         out-of-bounds keys in order to skip from the end of one range to the 
+         beginning of the next.
+
+         Consider the following example, where there is an index of field 
+         ``x`` and the collection contains 100 documents with ``x`` values 
+         1 through 100: 
+
+         .. code-block:: javascript
+
+            db.keys.find( { x : $in : [ 3, 4, 50, 74, 75, 90 ] } ).explain( "executionStats" )
+   
+         The query will scan keys ``3`` and ``4``. It will then scan the key 
+         ``5``, detect that it is out-of-bounds, and skip to the next key 
+         ``50``. 
+
+         Continuing this process, the query scans keys 
+         3, 4, 5, 50, 51, 74, 75, 76, 90, and 91. Keys 
+         ``5``, ``51``, ``76``, and ``91`` are out-of-bounds keys that are 
+         still examined. The value of ``keysExamined`` is 10. 
+
+      .. data:: explain.executionStats.executionStages.inputStage.docsExamined
+      
+         Specifies the number of documents scanned during the 
+         query execution stage.
+         
+         Present for the ``COLLSCAN`` stage, as well as for stages that 
+         retrieve documents from the collection (e.g. ``FETCH``)
 
    .. data:: explain.executionStats.allPlansExecution
 

source/release-notes/3.2.txt

@@ -747,6 +747,22 @@ addition to the numbers corresponding to the BSON types.
 :method:`db.collection.distinct()` method. For more information, see
 :method:`db.collection.explain()`.
 
+``keysExamined`` Statistic Corrected
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :method:`explain()` method's output in ``executionStats`` or 
+``allPlansExecution`` mode contains the ``keysExamined`` statistic, 
+representing the number of index keys examined during index scans. 
+It is also reported in the diagnostic logs and the system profiler.
+
+An accounting error prior to 3.2 resulted in the last scanned key not being 
+included in the ``keysExamined`` count for some queries. 
+As of 3.2 this error has been corrected. 
+
+See :data:`keysExamined
+<explain.executionStats.executionStages.inputStage.keysExamined>` 
+for more information.
+
 .. _3.2-relnotes-2dsphere-index:
 
 Geospatial Optimization