configureQueryAnalyzer
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:
Field | Type | Necessity | Description |
---|---|---|---|
configureQueryAnalyzer | string | Required | namespace of the collection to configure for query
sampling. |
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.
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 analyzedclusterManager
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) | samplesPerSecond | Sampling Duration (Days) | Number of Sampled Queries | Total Size of Sampled Queries (GB) |
---|---|---|---|---|
0.5 | 0.1 | 7 | 60,480 | 0.03024 |
0.5 | 10 | 7 | 6,048,000 | 3.024 |
0.5 | 50 | 7 | 30,240,000 | 15.12 |
1000 | 50 | 1 | 4,320,000 | 4320 |
16,000 | 50 | 1 | 432,0000 | 69,120 |
queryAnalysisSampleExpirationSecs
Sampled queries are stored in an internal collection that has a TTL
index with expireAfterSeconds
. To configure expireAfterSeconds
,
use the queryAnalysisSampleExpirationSecs
server parameter.
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 amongos
.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" } )