planCacheListPlans.txt

==================
planCacheListPlans
==================

.. default-domain:: mongodb

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

Definition
----------

.. dbcommand:: planCacheListPlans

   .. versionadded:: 2.6

   Displays the cached query plans for the specified :term:`query
   shape`.

   .. include:: /includes/fact-query-optimizer-cache-behavior.rst

   The :binary:`~bin.mongo` shell provides the wrapper
   :method:`PlanCache.getPlansByQuery()` for this command.

   The :dbcommand:`planCacheListPlans` command has the following syntax:

   .. code-block:: javascript

      db.runCommand(
         {
            planCacheListPlans: <collection>,
            query: <query>,
            sort: <sort>,
            projection: <projection>
         }

   The :dbcommand:`planCacheListPlans` command has the following field:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Field
   
        - Type
   
        - Description
   
      * - ``query``
   
        - document
   
        - The query predicate of the :term:`query shape`. Only the structure
          of the predicate, including the field names, are significant to the
          shape; the values in the query predicate are insignificant.
          
          
   
      * - ``projection``
   
        - document
   
        - Optional. The projection associated with the :term:`query shape`.
          
          
   
      * - ``sort``
   
        - document
   
        - Optional. The sort associated with the :term:`query shape`.
          
          
   


   To see the query shapes for which cached query plans exist, use the
   :dbcommand:`planCacheListQueryShapes` command.

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

On systems running with :setting:`~security.authorization`, a user must have access that
includes the :authaction:`planCacheRead` action.

Example
-------

If a collection ``orders`` has the following query shape:

.. code-block:: javascript

     {
       "query" : { "qty" : { "$gt" : 10 } },
       "sort" : { "ord_date" : 1 },
       "projection" : { }
     }

The following operation displays the query plan cached for the shape:

.. code-block:: javascript

   db.runCommand(
      {
         planCacheListPlans: "orders",
         query: { "qty" : { "$gt" : 10 } },
         sort: { "ord_date" : 1 }
      }
   )

.. seealso::

   - :dbcommand:`planCacheListQueryShapes`
   - :method:`PlanCache.getPlansByQuery()`
   - :method:`PlanCache.listQueryShapes()`