Docs Home → MongoDB Manual

configureQueryAnalyzer

On this page本页内容

Definition

configureQueryAnalyzer

New in version 7.0.

Configures query sampling for a collection on a replica set or sharded cluster. Sampled queries provide information to analyzeShardKey to calculate metrics about read and write distribution of a shard key.

Syntax

The command has the following syntax:

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

Command Fields

configureQueryAnalyzer has the following fields:

FieldTypeNecessityDescription
configureQueryAnalyzerstringRequirednamespace of the collection to configure for query sampling.
modestringRequiredMode the query analyzer runs in. Must be set to either "full" or "off".
samplesPerSeconddoubleOptionalNumber 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 samplesPerSecond Upper Limit.

Access Control

configureQueryAnalyzer requires one of the following roles:

  • dbAdmin role against the database that contains the collection being analyzed
  • clusterManager role against the cluster

Behavior

Consider the following behavior when running configureQueryAnalyzer:

Dropped Collections and Renamed Collections

Query sampling is disabled automatically when the collection is dropped or renamed. If you want to sample queries after a collection is recreated or renamed, you must reconfigure query sampling.

samplesPerSeconds Upper Limit

The upper limit for samplesPerSecond is 50. A higher rate causes the sampled queries to fill up 10GB of disk space in less than four days.

This table shows the estimated disk usage for each sample rate and duration combination:

Average Sampled Query Size (kB)samplesPerSecondSampling Duration (Days)Number of Sampled QueriesTotal Size of Sampled Queries (GB)
0.50.1760,4800.03024
0.51076,048,0003.024
0.550730,240,00015.12
10005014,320,0004320
16,000501432,000069,120

queryAnalysisSampleExpirationSecs

Sampled queries are stored in an internal collection that has a TTL index with expireAfterSeconds. Configure expireAfterSeconds with the queryAnalysisSampleExpirationSecs server parameter. with the queryAnalysisSampleExpirationSecs. Sampled queries are automatically deleted after queryAnalysisSampleExpirationSecs.

Query Sampling Progress

When query sampling is enabled, you can check the progress of query sampling using the $currentOp aggregation stage.

Limitations

  • You cannot run configureQueryAnalyzer on Atlas multi-tenant configurations.
  • You cannot run configureQueryAnalyzer on standalone deployments.
  • You cannot run configureQueryAnalyzer directly against a --shardsvr replica set. When running on a sharded cluster, configureQueryAnalyzer must run against a mongos.
  • You cannot run configureQueryAnalyzer against time series collections.
  • You cannot run configureQueryAnalyzer against collections with Queryable Encryption.

Output

configureQueryAnalyzer returns a document containing fields that describe the old configuration, if one exists, and fields describing the new configuration.

  • oldConfiguration, if it exists, contains fields describing the old configuration.
  • newConfiguration contains fields describing the new configuration.

configureQueryAnalyzer returns a document similar to the following:

{
   ok: 1,
   oldConfiguration: {
     mode: ...,
     samplesPerSecond: ...
   }
   newConfiguration: {
     ...
   }
}

Query Sampling Progress

When query sampling is enabled, you can check the progress of the query sampling using the $currentOp aggregation stage.

For details on the query sampling-related fields, see the related fields.

Examples

Enable Query Sampling

To enable query sampling on the test.students collection at a rate of five samples per second, use the following command:

db.adminCommand(
   {
     configureQueryAnalyzer: "test.students",
     mode: "full",
     samplesPerSecond: 5
   }
)

Disable Query Sampling

To disable query sampling on the test.students collection, use the following command:

db.adminCommand(
   {
     configureQueryAnalyzer: "test.students",
     mode: "off"
   }
)

Learn More