db.collection.configureQueryAnalyzer.txt

.. _configureQueryAnalyzer-method:

======================================
db.collection.configureQueryAnalyzer()
======================================

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

Definition
----------

.. method:: db.collection.configureQueryAnalyzer(options)

   Configures query sampling for a collection on a replica set or
   sharded cluster. Sampled queries provide information to 
   :dbcommand:`analyzeShardKey` to calculate metrics about read and 
   write distribution of a shard key.
   
   The :method:`db.collection.configureQueryAnalyzer()` method wraps the
   :dbcommand:`configureQueryAnalyzer` command.

   :returns: 
      A document containing fields describing the old configuration, if
      one exists, and fields describing the new configuration. For
      details, see :ref:`<cqa-output>`.


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

.. |command| replace:: method

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

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

.. include:: /includes/fact-environments-atlas-support-no-free.rst

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

Syntax
------

The method has the following syntax:

.. code-block:: javascript

   db.collection.configureQueryAnalyzer( 
      {
        mode: <string>,
        samplesPerSecond: <double>
      } 
   )

Fields
~~~~~~

.. |CQA| replace:: ``db.collection.configureQueryAnalyzer()``

|CQA| has the following fields:

.. list-table::
   :header-rows: 1
   :widths: 10 10 10 70 
 
   * - Field
     - Type
     - Necessity
     - Description

   * - ``mode``
     - string
     - Required
     - Mode the query analyzer runs in. Must be set to either
       ``"full"`` or ``"off"``.

   * - ``samplesPerSecond``
     - double
     - Optional
     - Number of samples per second.

       - When ``mode`` is set to ``"full"``, ``samplesPerSecond`` must
         be set between ``0`` and ``50``.
       - When ``mode`` is set to ``"off"``, the server ignores
         ``samplesPerSecond``.

       For details, see :ref:`samplesPerSeconds Upper Limit 
       <samplesPerSecond-limit>`.

Access Control
--------------

For details, see :ref:`configureQueryAnalyzer Access Control 
<cqa-access-control>`.

Behavior
--------

For behavior, see :ref:`configureQueryAnalyzer Behavior 
<cqa-behavior>`.

Output
------

For details, see :ref:`configureQueryAnalyzer Output <cqa-output>`.

Examples
--------

For examples, see :ref:`configureQueryAnalyzer Examples 
<cqa-examples>`.

Learn More
----------

- :dbcommand:`analyzeShardKey`
- :dbcommand:`configureQueryAnalyzer`
- :pipeline:`$listSampledQueries`