From e8a34454d900c48c174bda4919811078ef259ed1 Mon Sep 17 00:00:00 2001 From: Joseph Dougherty Date: Tue, 4 May 2021 18:53:47 -0400 Subject: [PATCH] DOCS-14045 documents new explain fields --- .../fact-explain-results-categories.rst | 10 +++- source/reference/command/explain.txt | 17 ++++--- source/reference/method/cursor.explain.txt | 17 ++++--- .../method/db.collection.explain.txt | 50 ++++++++++--------- 4 files changed, 53 insertions(+), 41 deletions(-) diff --git a/source/includes/fact-explain-results-categories.rst b/source/includes/fact-explain-results-categories.rst index b6dadd263a7..673103782f2 100644 --- a/source/includes/fact-explain-results-categories.rst +++ b/source/includes/fact-explain-results-categories.rst @@ -1,14 +1,20 @@ |explain| operations can return information regarding: +- ``explainVersion``, the output format version (for example, ``"1"``); + +- ``command``, which details the command being explained; + - :ref:`queryPlanner`, which details the plan selected by the :doc:`query optimizer ` and lists the rejected plans; - :ref:`executionStats`, which details the execution of the winning - plan and the rejected plans; and + plan and the rejected plans; - :ref:`serverInfo`, which provides information on the - MongoDB instance. + MongoDB instance; and + +- ``serverParameters``, which details internal parameters. The verbosity mode (i.e. ``queryPlanner``, ``executionStats``, ``allPlansExecution``) determines whether the results include diff --git a/source/reference/command/explain.txt b/source/reference/command/explain.txt index 893d6e4193c..42e336856e5 100644 --- a/source/reference/command/explain.txt +++ b/source/reference/command/explain.txt @@ -144,6 +144,15 @@ Restrictions .. include:: /includes/extracts/4.2-changes-agg-out-explain.rst +.. _explain-command-output: + +Output +------ + +.. include:: /includes/fact-explain-results-categories.rst + +For details on the output, see :doc:`/reference/explain-results`. + Examples -------- @@ -216,11 +225,3 @@ all considered plans for an :dbcommand:`update` command: } ) -.. _explain-command-output: - -Output ------- - -.. include:: /includes/fact-explain-results-categories.rst - -For details on the output, see :doc:`/reference/explain-results`. diff --git a/source/reference/method/cursor.explain.txt b/source/reference/method/cursor.explain.txt index a924c1872c2..f02e859ef54 100644 --- a/source/reference/method/cursor.explain.txt +++ b/source/reference/method/cursor.explain.txt @@ -114,6 +114,15 @@ verbosity mode. See :method:`db.collection.explain()` for more information. +.. _explain-cursor-method-output: + +Output +------ + +.. include:: /includes/fact-explain-results-categories.rst + +For details on the output, see :doc:`/reference/explain-results`. + Example ------- @@ -128,11 +137,3 @@ specified :method:`db.collection.find()` operation: { quantity: { $gt: 50 }, category: "apparel" } ).explain("executionStats") -.. _explain-cursor-method-output: - -Output ------- - -.. include:: /includes/fact-explain-results-categories.rst - -For details on the output, see :doc:`/reference/explain-results`. diff --git a/source/reference/method/db.collection.explain.txt b/source/reference/method/db.collection.explain.txt index 609d3d5c70f..858fde38a5f 100644 --- a/source/reference/method/db.collection.explain.txt +++ b/source/reference/method/db.collection.explain.txt @@ -160,8 +160,9 @@ The :method:`db.collection.explain()` method wraps the .. include:: /includes/fact-explain-methods-differences.rst -:method:`db.collection.explain().aggregate() ` is equivalent to passing -the :ref:`explain ` option to +:method:`db.collection.explain().aggregate() ` +is equivalent to passing the +:ref:`explain ` option to the :method:`db.collection.aggregate()` method. .. _explain-method-help: @@ -176,10 +177,11 @@ To see the list of operations supported by db.collection.explain().help() -:method:`db.collection.explain().find() ` returns a cursor, which allows -for the chaining of query modifiers. To see the list of query modifiers -supported by :method:`db.collection.explain().find() -` as well as cursor-related methods, run: +:method:`db.collection.explain().find() ` +returns a cursor, which allows for the chaining of query modifiers. +To see the list of query modifiers supported by +:method:`db.collection.explain().find() ` as +well as cursor-related methods, run: .. code-block:: javascript @@ -188,6 +190,15 @@ supported by :method:`db.collection.explain().find() You can chain multiple modifiers to ``db.collection.explain().find()``. For an example, see :ref:`explain-find-modifiers`. +.. _explain-collection-method-output: + +Output +------ + +.. include:: /includes/fact-explain-results-categories.rst + +For details on the output, see :doc:`/reference/explain-results`. + .. _explain-method-examples: Examples @@ -250,9 +261,10 @@ all considered plans for the specified Explain ``find()`` with Modifiers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:method:`db.collection.explain().find() ` construct allows for the -chaining of query modifiers. For example, the following operation -provides information on the :method:`~db.collection.find()` method with +:method:`db.collection.explain().find() ` +construct allows for the chaining of query modifiers. For example, the +following operation provides information on the +:method:`~db.collection.find()` method with :method:`~cursor.sort()` and :method:`~cursor.hint()` query modifiers. .. code-block:: javascript @@ -271,22 +283,14 @@ shell: Iterate the ``explain().find()`` Return Cursor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:method:`db.collection.explain().find() ` returns a cursor to the -explain results. If run interactively in the :binary:`~bin.mongo` shell, -the :binary:`~bin.mongo` shell automatically iterates the cursor using the -``.next()`` method. For scripts, however, you must explicitly call -``.next()`` (or its alias ``.finish()``) to return the results: +:method:`db.collection.explain().find() ` +returns a cursor to the explain results. If run interactively in the +:binary:`~bin.mongo` shell, the :binary:`~bin.mongo` shell automatically +iterates the cursor using the ``.next()`` method. For scripts, however, +you must explicitly call ``.next()`` (or its alias ``.finish()``) to +return the results: .. code-block:: javascript var explainResult = db.products.explain().find( { category: "apparel" } ).next(); -.. _explain-collection-method-output: - -Output ------- - -.. include:: /includes/fact-explain-results-categories.rst - -For details on the output, see :doc:`/reference/explain-results`. -