diff --git a/bin/htaccess.yaml b/bin/htaccess.yaml index 303a86eb8c7..2ea22bcc04e 100644 --- a/bin/htaccess.yaml +++ b/bin/htaccess.yaml @@ -1482,6 +1482,14 @@ outputs: - 'after-v2.2' - 'manual' --- +redirect-path: '/reference/explain' +url-base: '/reference/method/cursor.explain' +type: 'redirect' +code: 301 +outputs: + - 'after-v2.2' + - 'manual' +--- redirect-path: '/reference/meta-query-operators' url-base: '/reference/operator/query-modifier' type: 'redirect' diff --git a/source/core/read-operations.txt b/source/core/read-operations.txt index 0b7c59b0591..01a4e2c9d2f 100644 --- a/source/core/read-operations.txt +++ b/source/core/read-operations.txt @@ -688,7 +688,7 @@ use of the different indexes: This returns the statistics regarding the execution of the query. For more information on the output of :method:`explain() -`, see the :doc:`/reference/explain`. +`, see :doc:`/reference/method/cursor.explain`. .. note:: diff --git a/source/reference.txt b/source/reference.txt index e3af8e11397..4ad9431b623 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -45,7 +45,7 @@ Status and Reporting :maxdepth: 1 reference/database-profiler - reference/explain + reference/method/cursor.explain reference/exit-codes Internal Metadata diff --git a/source/reference/explain.txt b/source/reference/explain.txt deleted file mode 100644 index 69b3a44dfab..00000000000 --- a/source/reference/explain.txt +++ /dev/null @@ -1,321 +0,0 @@ -============== -Explain Output -============== - -.. default-domain:: mongodb - -This document explains the output of the :operator:`$explain` operator -and the :program:`mongo` shell method :method:`~cursor.explain()`. - -Explain Output --------------- - -The :ref:`explain-output-fields-core` fields display information for -queries on non-sharded collections. For queries on sharded collections, -:method:`~cursor.explain()` returns this information for each -shard the query accesses. - -.. code-block:: javascript - - { - "cursor" : "", - "isMultiKey" : , - "n" : , - "nscannedObjects" : , - "nscanned" : , - "nscannedObjectsAllPlans" : , - "nscannedAllPlans" : , - "scanAndOrder" : , - "indexOnly" : , - "nYields" : , - "nChunkSkips" : , - "millis" : , - "indexBounds" : { }, - "allPlans" : [ - { "cursor" : "", - "n" : , - "nscannedObjects" : , - "nscanned" : , - "indexBounds" : { } - }, - ... - ], - "oldPlan" : { - "cursor" : "", - "indexBounds" : { } - } - "server" : "", - } - -``$or`` Queries ---------------- - -Queries with :operator:`$or` operator execute each clause of the -:operator:`$or` expression in parallel and can use separate indexes on -the individual clauses. If the query uses indexes on any or all of the -query's clause, :method:`explain() ` contains -:ref:`output ` for each clause as well as -the cumulative data for the entire query: - -.. code-block:: javascript - - { - "clauses" : [ - { - - }, - { - - }, - ... - ], - "n" : , - "nscannedObjects" : , - "nscanned" : , - "nscannedObjectsAllPlans" : , - "nscannedAllPlans" : , - "millis" : , - "server" : "" - } - -Sharded Collections -------------------- - -For queries on a sharded collection, the output contains the -:ref:`explain-output-fields-core` for each accessed shard and -:ref:`cumulative shard information `: - -.. code-block:: javascript - - { - "clusteredType" : "", - "shards" : { - - "" : [ - { - - } - ], - "" : [ - { - - } - ], - ... - }, - "millisShardTotal" : , - "millisShardAvg" : , - "numQueries" : , - "numShards" : , - "cursor" : "", - "n" : , - "nChunkSkips" : , - "nYields" : , - "nscanned" : , - "nscannedAllPlans" : , - "nscannedObjects" : , - "nscannedObjectsAllPlans" : , - "millis" : - } - -Fields ------- - -.. _explain-output-fields-core: - -Core Explain Output -~~~~~~~~~~~~~~~~~~~ - -.. data:: explain.cursor - - :data:`~explain.cursor` is a string that reports the type of cursor - used by the query operation: - - - ``BasicCursor`` indicates a full collection scan. - - - ``BtreeCursor`` indicates that the query used an index. The - cursor includes name of the index. When a query uses an index, - the output of :method:`explain() ` includes - :data:`~explain.indexBounds` details. - - - ``GeoSearchCursor`` indicates that the query used a geospatial - index. - -.. data:: explain.isMultiKey - - :data:`~explain.isMultiKey` is a boolean. When ``true``, the query uses a - :ref:`multikey index `, where one of the - fields in the index holds an array. - -.. data:: explain.n - - :data:`~explain.n` is a number that reflects the number of documents - that match the query selection criteria. - -.. data:: explain.nscannedObjects - - Specifies the total number of documents scanned during the query. - The :data:`~explain.nscannedObjects` may be lower than - :data:`~explain.nscanned`, such as if the index :ref:`covers - ` a query. See - :data:`~explain.indexOnly`. Additionally, the - :data:`~explain.nscannedObjects` may be lower than - :data:`~explain.nscanned` in the case of multikey index on an array - field with duplicate documents. - -.. data:: explain.nscanned - - Specifies the total number of documents or index entries scanned - during the database operation. You want :data:`~explain.n` and - :data:`~explain.nscanned` to be close in value as possible. The - :data:`~explain.nscanned` value may be higher than the - :data:`~explain.nscannedObjects` value, such as if the index :ref:`covers - ` a query. See :data:`~explain.indexOnly`. - -.. data:: explain.nscannedObjectsAllPlans - - .. versionadded:: 2.2 - - :data:`~explain.nscannedObjectsAllPlans` is a number that reflects the - total number of documents scanned for all query plans during the - database operation. - -.. data:: explain.nscannedAllPlans - - .. versionadded:: 2.2 - - :data:`~explain.nscannedAllPlans` is a number that reflects the total - number of documents or index entries scanned for all query plans - during the database operation. - -.. data:: explain.scanAndOrder - - :data:`~explain.scanAndOrder` is a boolean that is ``true`` when - the query **cannot** use the index for returning sorted results. - - When ``true``, MongoDB must sort the documents after it retrieves - them from either an index cursor or a cursor that scans the entire - collection. - -.. data:: explain.indexOnly - - :data:`~explain.indexOnly` is a boolean value that returns ``true`` - when the query is :ref:`covered ` by - the index indicated in the :data:`~explain.cursor` field. When an - index covers a query, MongoDB can both match the :ref:`query - conditions ` **and** return the - results using only the index because: - - - all the fields in the :ref:`query - ` are part of that index, **and** - - - all the fields returned in the results set are in the same index. - -.. data:: explain.nYields - - :data:`~explain.nYields` is a number that reflects the number of times - this query yielded the read lock to allow waiting writes execute. - -.. data:: explain.nChunkSkips - - :data:`~explain.nChunkSkips` is a number that reflects the number of - documents skipped because of active chunk migrations in a sharded - system. Typically this will be zero. A number greater than zero is - ok, but indicates a little bit of inefficiency. - -.. data:: explain.millis - - :data:`~explain.millis` is a number that reflects the time in - milliseconds to complete the query. - -.. data:: explain.indexBounds - - :data:`~explain.indexBounds` is a document that contains the lower and upper - index key bounds. This field resembles one of the following: - - .. code-block:: javascript - - "indexBounds" : { - "start" : { : , ... }, - "end" : { : , ... } - }, - - .. code-block:: javascript - - "indexBounds" : { "" : [ [ , ] ], - ... - } - -.. data:: explain.allPlans - - :data:`~explain.allPlans` is an array that holds the list of plans - the query optimizer runs in order to select the index for the query. - Displays only when the ```` parameter to :method:`explain() - ` is ``true`` or ``1``. - -.. data:: explain.oldPlan - - .. versionadded:: 2.2 - - :data:`~explain.oldPlan` is a document value that contains the previous plan - selected by the query optimizer for the query. Displays only when - the ```` parameter to :method:`explain() - ` is ``true`` or ``1``. - -.. data:: explain.server - - .. versionadded:: 2.2 - - :data:`~explain.server` is a string that reports the MongoDB server. - -.. _explain-output-field-or-clauses: - -``$or`` Query Output -~~~~~~~~~~~~~~~~~~~~ - -.. data:: explain.clauses - - :data:`~explain.clauses` is an array that holds the - :ref:`explain-output-fields-core` information for each clause of the - :operator:`$or` expression. :data:`~explain.clauses` is only included when - the clauses in the :operator:`$or` expression use indexes. - -.. _explain-output-fields-sharded-collection: - -Sharded Collections Output -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. data:: explain.clusteredType - - :data:`~explain.clusteredType` is a string that reports the access - pattern for shards. The value is: - - - ``ParallelSort``, if the :program:`mongos` queries shards in parallel. - - - ``SerialServer``, if the :program:`mongos` queries shards sequentially. - -.. data:: explain.shards - - :data:`~explain.shards` contains fields for each shard in the - cluster accessed during the query. Each field holds the - :ref:`explain-output-fields-core` for that shard. - -.. data:: explain.millisShardTotal - - :data:`~explain.millisShardTotal` is a number that reports the total - time in milliseconds for the query to run on the shards. - -.. data:: explain.millisShardAvg - - :data:`~explain.millisShardAvg` is a number that reports the average - time in millisecond for the query to run on each shard. - -.. data:: explain.numQueries - - :data:`~explain.numQueries` is a number that reports the total number - of queries executed. - -.. data:: explain.numShards - - :data:`~explain.numShards` is a number that reports the total number of - shards queried. diff --git a/source/reference/method/cursor.explain.txt b/source/reference/method/cursor.explain.txt index 38feb8df6ec..2d3175c6129 100644 --- a/source/reference/method/cursor.explain.txt +++ b/source/reference/method/cursor.explain.txt @@ -7,6 +7,9 @@ cursor.explain() .. EDITS to cursor.explain.txt must be carried over to the operator explain.txt and vice versa +Definition +---------- + .. method:: cursor.explain() The :method:`cursor.explain()` method provides information on the @@ -17,11 +20,10 @@ cursor.explain() :param boolean verbose: Specifies the level of detail to include in the output. If - ``true`` or ``1``, include the ``allPlans`` and ``oldPlan`` - fields in the :doc:`output document - `. + ``true`` or ``1``, includes the ``allPlans`` and ``oldPlan`` + fields in the output. - :returns: A :doc:`document ` that + :returns: A document that describes the process used to return the query results. Retrieve the query plan by appending :method:`~cursor.explain()` to @@ -32,8 +34,6 @@ cursor.explain() db.products.find().explain() - For details on the output, see :doc:`/reference/explain`. - :method:`explain ` runs the actual query to determine the result. Although there are some differences between running the query with :method:`explain ` and @@ -86,3 +86,315 @@ cursor.explain() information regarding the database profile. - :doc:`Current Operation Reporting ` + +Output for Queries on Sharded Collections +----------------------------------------- + +This section explains output for queries on sharded collections. For +queries on non-sharded collections, see +:ref:`explain-output-fields-core`. + +For queries on sharded collections, :method:`~cursor.explain()` returns +information for each shard the query accesses. + +.. code-block:: javascript + + { + "cursor" : "", + "isMultiKey" : , + "n" : , + "nscannedObjects" : , + "nscanned" : , + "nscannedObjectsAllPlans" : , + "nscannedAllPlans" : , + "scanAndOrder" : , + "indexOnly" : , + "nYields" : , + "nChunkSkips" : , + "millis" : , + "indexBounds" : { }, + "allPlans" : [ + { "cursor" : "", + "n" : , + "nscannedObjects" : , + "nscanned" : , + "indexBounds" : { } + }, + ... + ], + "oldPlan" : { + "cursor" : "", + "indexBounds" : { } + } + "server" : "", + } + +``$or`` Queries +~~~~~~~~~~~~~~~ + +Queries with :operator:`$or` operator execute each clause of the +:operator:`$or` expression in parallel and can use separate indexes on +the individual clauses. If the query uses indexes on any or all of the +query's clause, :method:`explain() ` contains +:ref:`output ` for each clause as well as +the cumulative data for the entire query: + +.. code-block:: javascript + + { + "clauses" : [ + { + + }, + { + + }, + ... + ], + "n" : , + "nscannedObjects" : , + "nscanned" : , + "nscannedObjectsAllPlans" : , + "nscannedAllPlans" : , + "millis" : , + "server" : "" + } + +Sharded Collections +~~~~~~~~~~~~~~~~~~~ + +For queries on a sharded collection, the output contains the +:ref:`explain-output-fields-core` for each accessed shard and +:ref:`cumulative shard information `: + +.. code-block:: javascript + + { + "clusteredType" : "", + "shards" : { + + "" : [ + { + + } + ], + "" : [ + { + + } + ], + ... + }, + "millisShardTotal" : , + "millisShardAvg" : , + "numQueries" : , + "numShards" : , + "cursor" : "", + "n" : , + "nChunkSkips" : , + "nYields" : , + "nscanned" : , + "nscannedAllPlans" : , + "nscannedObjects" : , + "nscannedObjectsAllPlans" : , + "millis" : + } + +.. _explain-output-fields-core: + +Core Explain Output +------------------- + +.. data:: explain.cursor + + :data:`~explain.cursor` is a string that reports the type of cursor + used by the query operation: + + - ``BasicCursor`` indicates a full collection scan. + + - ``BtreeCursor`` indicates that the query used an index. The + cursor includes name of the index. When a query uses an index, + the output of :method:`explain() ` includes + :data:`~explain.indexBounds` details. + + - ``GeoSearchCursor`` indicates that the query used a geospatial + index. + +.. data:: explain.isMultiKey + + :data:`~explain.isMultiKey` is a boolean. When ``true``, the query uses a + :ref:`multikey index `, where one of the + fields in the index holds an array. + +.. data:: explain.n + + :data:`~explain.n` is a number that reflects the number of documents + that match the query selection criteria. + +.. data:: explain.nscannedObjects + + Specifies the total number of documents scanned during the query. + The :data:`~explain.nscannedObjects` may be lower than + :data:`~explain.nscanned`, such as if the index :ref:`covers + ` a query. See + :data:`~explain.indexOnly`. Additionally, the + :data:`~explain.nscannedObjects` may be lower than + :data:`~explain.nscanned` in the case of multikey index on an array + field with duplicate documents. + +.. data:: explain.nscanned + + Specifies the total number of documents or index entries scanned + during the database operation. You want :data:`~explain.n` and + :data:`~explain.nscanned` to be close in value as possible. The + :data:`~explain.nscanned` value may be higher than the + :data:`~explain.nscannedObjects` value, such as if the index :ref:`covers + ` a query. See :data:`~explain.indexOnly`. + +.. data:: explain.nscannedObjectsAllPlans + + .. versionadded:: 2.2 + + :data:`~explain.nscannedObjectsAllPlans` is a number that reflects the + total number of documents scanned for all query plans during the + database operation. + +.. data:: explain.nscannedAllPlans + + .. versionadded:: 2.2 + + :data:`~explain.nscannedAllPlans` is a number that reflects the total + number of documents or index entries scanned for all query plans + during the database operation. + +.. data:: explain.scanAndOrder + + :data:`~explain.scanAndOrder` is a boolean that is ``true`` when + the query **cannot** use the index for returning sorted results. + + When ``true``, MongoDB must sort the documents after it retrieves + them from either an index cursor or a cursor that scans the entire + collection. + +.. data:: explain.indexOnly + + :data:`~explain.indexOnly` is a boolean value that returns ``true`` + when the query is :ref:`covered ` by + the index indicated in the :data:`~explain.cursor` field. When an + index covers a query, MongoDB can both match the :ref:`query + conditions ` **and** return the + results using only the index because: + + - all the fields in the :ref:`query + ` are part of that index, **and** + + - all the fields returned in the results set are in the same index. + +.. data:: explain.nYields + + :data:`~explain.nYields` is a number that reflects the number of times + this query yielded the read lock to allow waiting writes execute. + +.. data:: explain.nChunkSkips + + :data:`~explain.nChunkSkips` is a number that reflects the number of + documents skipped because of active chunk migrations in a sharded + system. Typically this will be zero. A number greater than zero is + ok, but indicates a little bit of inefficiency. + +.. data:: explain.millis + + :data:`~explain.millis` is a number that reflects the time in + milliseconds to complete the query. + +.. data:: explain.indexBounds + + :data:`~explain.indexBounds` is a document that contains the lower and upper + index key bounds. This field resembles one of the following: + + .. code-block:: javascript + + "indexBounds" : { + "start" : { : , ... }, + "end" : { : , ... } + }, + + .. code-block:: javascript + + "indexBounds" : { "" : [ [ , ] ], + ... + } + +.. data:: explain.allPlans + + :data:`~explain.allPlans` is an array that holds the list of plans + the query optimizer runs in order to select the index for the query. + Displays only when the ```` parameter to :method:`explain() + ` is ``true`` or ``1``. + +.. data:: explain.oldPlan + + .. versionadded:: 2.2 + + :data:`~explain.oldPlan` is a document value that contains the previous plan + selected by the query optimizer for the query. Displays only when + the ```` parameter to :method:`explain() + ` is ``true`` or ``1``. + +.. data:: explain.server + + .. versionadded:: 2.2 + + :data:`~explain.server` is a string that reports the MongoDB server. + +.. _explain-output-field-or-clauses: + +``$or`` Query Output +~~~~~~~~~~~~~~~~~~~~ + +.. data:: explain.clauses + + :data:`~explain.clauses` is an array that holds the + :ref:`explain-output-fields-core` information for each clause of the + :operator:`$or` expression. :data:`~explain.clauses` is only included when + the clauses in the :operator:`$or` expression use indexes. + +.. _explain-output-fields-sharded-collection: + +Sharded Collections Output +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. data:: explain.clusteredType + + :data:`~explain.clusteredType` is a string that reports the access + pattern for shards. The value is: + + - ``ParallelSort``, if the :program:`mongos` queries shards in parallel. + + - ``SerialServer``, if the :program:`mongos` queries shards sequentially. + +.. data:: explain.shards + + :data:`~explain.shards` contains fields for each shard in the + cluster accessed during the query. Each field holds the + :ref:`explain-output-fields-core` for that shard. + +.. data:: explain.millisShardTotal + + :data:`~explain.millisShardTotal` is a number that reports the total + time in milliseconds for the query to run on the shards. + +.. data:: explain.millisShardAvg + + :data:`~explain.millisShardAvg` is a number that reports the average + time in millisecond for the query to run on each shard. + +.. data:: explain.numQueries + + :data:`~explain.numQueries` is a number that reports the total number + of queries executed. + +.. data:: explain.numShards + + :data:`~explain.numShards` is a number that reports the total number of + shards queried. diff --git a/source/reference/operator/explain.txt b/source/reference/operator/explain.txt index e839169f3d8..36cdcadb59f 100644 --- a/source/reference/operator/explain.txt +++ b/source/reference/operator/explain.txt @@ -10,25 +10,26 @@ $explain .. operator:: $explain The :operator:`$explain` operator provides information on the query - plan. It returns a :doc:`document ` that describes + plan. It returns a document that describes the process and indexes used to return the query. This may provide useful insight when attempting to optimize a query. + For details on the output, see :doc:`/reference/method/cursor.explain`. - :program:`mongo` shell also provides the :method:`explain() - ` method: + You can specify the :operator:`$explain` operator in either of the + following forms: .. code-block:: javascript - db.collection.find().explain() + db.collection.find()._addSpecial( "$explain", 1 ) + db.collection.find( { $query: {}, $explain: 1 } ) - You can also specify the option in either of the following forms: + You also can specify :operator:`$explain` through the + :method:`explain() ` method in the :program:`mongo` + shell: .. code-block:: javascript - db.collection.find()._addSpecial( "$explain", 1 ) - db.collection.find( { $query: {}, $explain: 1 } ) - - For details on the output, see :doc:`/reference/explain`. + db.collection.find().explain() :operator:`$explain` runs the actual query to determine the result. Although there are some differences between running the query with