PlanCache.clearPlansByQuery.txt

=============================
PlanCache.clearPlansByQuery()
=============================

.. default-domain:: mongodb

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

Definition
----------

.. method:: PlanCache.clearPlansByQuery( <query>, <projection>, <sort> )

   Clears the cached query plans for the specified :term:`plan cache query shape`.

   .. |dbcommand| replace:: :dbcommand:`planCacheClear` command
   .. include:: /includes/fact-mongosh-shell-method-alt

   The method is only available from the :method:`plan cache object
   <db.collection.getPlanCache()>` of a specific collection; i.e.

   .. code-block:: javascript

      db.collection.getPlanCache().clearPlansByQuery( <query>, <projection>, <sort> )

   The :method:`PlanCache.clearPlansByQuery()` method accepts the
   following parameters:


   .. list-table::
      :header-rows: 1
      :widths: 20 20 80
   
      * - Parameter
   
        - Type
   
        - Description
   
      * - ``query``
   
        - document
   
        - The query predicate of the plan cache 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 plan cache query shape. Required if
          specifying the ``sort`` parameter.
          
          
   
      * - ``sort``
   
        - document
   
        - Optional. The sort associated with the plan cache query shape.

   To see the query shapes for which cached query plans exist, see
   :ref:`planCacheStats-examples`.

.. include:: /includes/persistent-query-settings-avoid-index-filters-intro.rst

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

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

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

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

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

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

Example
-------

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

.. code-block:: javascript

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

.. warning::

   .. include:: /includes/plan-cache-rename.rst

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

.. code-block:: javascript

   db.orders.getPlanCache().clearPlansByQuery(
      { "qty" : { "$gt" : 10 } },
      { },
      { "ord_date" : 1 }
   )

.. seealso::

   - :method:`db.collection.getPlanCache()`
   - ``PlanCache.listQueryShapes()``
   - :method:`PlanCache.clear()`