cursor.explain.txt

================
cursor.explain()
================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol

Definition
----------

.. method:: cursor.explain(verbosity)

   .. include:: /includes/fact-mongosh-shell-method.rst

   Provides information on the query plan for the
   :method:`db.collection.find()` method.

   The ``explain()`` method has the following form:

   .. code-block:: javascript

      db.collection.find().explain()

   The ``explain()`` method has the following parameter:

   .. list-table::
      :header-rows: 1
      :widths: 20 10 10 80
   
      * - Parameter
        - Necessity
        - Type
        - Description
   
      * - ``verbose``
        - Optional
        - String
        - Determines the amount of information to include in the explain
          output. The possible verbosity modes are:
          
          - ``allPlansExecution``
          - ``executionStats``
          - ``queryPlanner`` (*Default*)
          
          For backwards compatibility with earlier versions of
          ``explain()``, MongoDB interprets ``true`` as
          ``allPlansExecution`` and ``false`` as ``queryPlanner``.
          
          For more information on the modes, see
          :ref:`explain-cursor-method-verbosity`.


   The :method:`~cursor.explain()` method returns a document with the
   query plan and, optionally, the execution statistics.

Compatibility
-------------

This method is available in deployments hosted in the following environments: 

.. include:: /includes/fact-environments-atlas-only.rst

.. include:: /includes/fact-environments-atlas-support-all.rst

.. include:: /includes/fact-environments-onprem-only.rst

Required Access
---------------

.. include:: /includes/explain-required-access.rst

Behavior
--------

.. include:: includes/explain-ignores-cache-plan.rst

.. _explain-cursor-method-verbosity:

Verbosity Modes
~~~~~~~~~~~~~~~

The behavior of :method:`cursor.explain()` and the amount of
information returned depend on the ``verbosity`` mode.

.. |explain| replace:: :method:`cursor.explain()`
.. |operation| replace:: method

.. _explain-cursor-method-queryPlanner:

``queryPlanner`` Mode
``````````````````````

By default, :method:`cursor.explain()` runs in ``queryPlanner``
verbosity mode.

.. include:: /includes/fact-explain-verbosity-queryPlanner.rst

.. _explain-cursor-method-executionStats:

``executionStats`` Mode
```````````````````````

.. include:: /includes/fact-explain-verbosity-executionStats.rst
   :end-before: start-explain-write

.. include:: /includes/fact-explain-verbosity-executionStats.rst
   :start-after: end-explain-write

.. _explain-cursor-method-allPlansExecution:

``allPlansExecution`` Mode
``````````````````````````

.. include:: /includes/fact-explain-verbosity-allPlansExecution.rst
   :end-before: start-explain-write

.. include:: /includes/fact-explain-verbosity-allPlansExecution.rst
   :start-after: end-explain-write

``db.collection.explain().find()``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-explain-methods-differences.rst

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
-------

The following example runs :method:`cursor.explain()` in
:ref:`"executionStats" <explain-method-executionStats>` verbosity mode
to return the query planning and execution information for the
specified :method:`db.collection.find()` operation:

.. code-block:: javascript

   db.products.find(
      { quantity: { $gt: 50 }, category: "apparel" }
   ).explain("executionStats")