Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 42 additions & 4 deletions source/reference/explain-results.txt
Original file line number Diff line number Diff line change
Expand Up @@ -181,8 +181,10 @@ information:
"inputStage" : {
"stage" : <STAGE2>,
...
"nReturned" : 0,
"nReturned" : <int>,
"executionTimeMillisEstimate" : <int>,
"keysExamined" : <int>,
"docsExamined" : <int>,
...
"inputStage" : {
...
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand Down
16 changes: 16 additions & 0 deletions source/release-notes/3.2.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's move most of this into the /source/reference/explain-results.txt page and try to have a short summary (linking to what you write in the explain-results page) for the 3.2 release notes page.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@rkumar-mongo I don't see the update here. Did you push?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I force pushed - it seems to have stomped over whatever was there before, so its now in a state reflecting the changes, rather than what kay commented on. Which is what force does I suppose.

``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
Expand Down