You can monitor operation-level query execution metrics for query shapes with slow-running queries using Query Shape Insights. The Query Shape Insights page displays charts and a table that describe the performance metrics for the query shapes in your project with the highest total execution time. You can filter the displayed query shape data by host, shard, and time range, and select up to five query shapes to visualize in the corresponding metric charts.
Atlas supports Query Shape Insights on only dedicated clusters (M10 and above) running MongoDB version 8.0 and above.
How Atlas Collects Query Shape Statistics
Query Shape Insights displays data from a subset of the operations that run on your cluster. The collection method depends on your cluster's MongoDB version:
On clusters running MongoDB 8.x, Atlas records up to 100 read queries per second on each host. Atlas does not collect write operations.
On clusters running MongoDB 9.0 or later, Atlas randomly samples 1% of read and write operations by default. Displayed metric values reflect only sampled operations, approximately 1% of total operations. Query shapes that run infrequently may not appear in the results. This method also collects write operations (
insert,update, anddelete), which appear in Query Shape Insights alongside read operations.
Note
After you upgrade a cluster from MongoDB 8.x to 9.0, metric totals in Query Shape Insights may appear significantly different than before the upgrade. This difference reflects the change in sampling method, not a change in your cluster's workload.
Required Access
To view metrics with Query Shape Insights, you must have Project Observability Viewer, Project Data Access Read Only, Project Data Access Read/Write, Project Data Access Admin, or Project Owner access to the project.
Important
Query shapes exposing field names but redacted values may contain user PII. To view truncated or full query shapes in Query Shape Insights, you must have one of the project roles listed above, which each give access to view PII. For users without these permissions, Query Shape Insights identifies query shapes by their query shape hash.
Access Query Shape Insights
To access Query Shape Insights:
In Atlas, go to the Clusters page for your project.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click Clusters under the Database heading.
The Clusters page displays.
Filter Query Insights
You can filter the Query Insights page by node, node state (primary or secondary), and shard. You can also filter by a custom date range within the last seven days, or select one of the following preset time ranges:
7 days
5 days
2 days
24 hours (default)
12 hours
8 hours
1 hour
When you apply a filter, Atlas re-fetches data for the charts and table on the current screen.
Note
Analytics nodes are included when you filter by secondary node state.
View Metrics in Charts and Tables
Query Shape Insights displays charts and a table that describe metrics for query shapes in your project with slow-running queries.
The Query Shape Insights table contains one row for each top query shape in your project, where top query shapes are determined by highest total execution time. Each row contains the query shape or its query shape hash, the namespace of the query shape, the query command, and any metrics that you select to display. You can use the Edit Columns button to choose which of the following metrics to include as table columns:
Metric | Description |
|---|---|
Total Execution Time | |
Avg Execution Time | |
Execution Count | Total number of times that queries with the given query shape have been executed. |
Keys Examined | Total number of in-bounds and out-of-bounds index keys examined by queries with the given query shape. |
Keys Examined:Returned | Ratio of in-bounds and out-of-bounds index keys examined to indexes containing documents returned by queries with the given query shape. |
Docs Examined | Total number of documents examined by queries with the given query shape. |
Docs Returned | Total number of documents returned by queries with the given query shape. |
Docs Examined:Returned | Ratio of documents examined to documents returned by queries with the given query shape. |
Docs Matched | Total number of documents matched by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Docs Modified | Total number of documents modified by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Docs Upserted | Total number of documents upserted by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Docs Inserted | Total number of documents inserted by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Docs Deleted | Total number of documents deleted by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Keys Inserted | Total number of index keys inserted by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Keys Deleted | Total number of index keys deleted by queries with the given query shape. Available only for write commands on clusters running MongoDB 9.0 or later. |
Total Time to Response | Time in microseconds spent from the beginning of query processing to the first server response. |
Last Execution Time | Execution runtime in microseconds for the most recent query with the given query shape. |
P50 Execution Time | 50th percentile in the execution time histogram. |
P90 Execution Time | 90th percentile in the execution time histogram. |
P99 Execution Time | 99th percentile in the execution time histogram. |
You can also display charts for one or more of the metrics above by selecting each metric that you want to chart from the drop-down menu in the Query Shape Statistics component header.
Atlas can chart each metric for up to five query shapes at a time. By default, Atlas charts each metric for the five query shapes with the highest Total Execution Time. You can choose to chart different query shapes by selecting or deselecting the checkbox in the row of your desired query shapes. You can manage which query shapes to chart from the table, by selecting or deselecting the checkbox in the row of your desired query shapes.
To view more details about a query shape, click on the row for the query shape to open the Query Shape Details view. This view contains the full query shape and query shape hash, each table metric listed above, and the following additional metrics:
Last Seen Timestamp
First Seen Timestamp
Last Seen Application
Last Seen Driver Name and Version
First Seen Application
First Seen Driver Name and Version
Query Shape Reports
Atlas can send you a Query Shape Report email that summarizes inefficient query shapes for a cluster in your project. To help you identify and investigate slow queries, the report links directly to the Query Shape Insights page.
Eligibility
Atlas automatically subscribes a project to Query Shape Reports when the project meets the following criteria:
The project receives a
Query Targeting: Scanned Objects / Returnedalert.The alert originates from a dedicated cluster (M10 or above) running MongoDB version 8.0 or above.
Project Owner users can also manually subscribe to or unsubscribe from Query Shape Reports regardless of whether the project has received a query targeting alert. To learn more, see Manage Report Subscriptions.
Report Behavior
Atlas sends Query Shape Reports on the following schedule:
When a project becomes eligible, Atlas sends the first report approximately one hour after the
Query Targeting: Scanned Objects / Returnedalert.Atlas sends additional reports approximately once per week until the project unsubscribes.
Atlas sends each report to all users with the Project Owner role.
If no qualifying query shapes exist for a given reporting period, Atlas skips that report and resumes with the next scheduled report.
Report Contents
Each Query Shape Report email contains the following information:
Links to the organization, project, and cluster in the Atlas UI.
A link to the Query Shape Insights page for the cluster.
A table of up to five query shapes, ranked by total execution time. Each query shape must have at least 10 executions in the reporting period to appear.
A link to each query shape's details on the Query Shape Insights page.
A link to the report subscription settings in Project Settings. To learn more, see Manage Project Settings.
The query shape table includes the following metrics for each query shape over the past three days:
Column | Description |
|---|---|
Collection Name | Name of the collection that the query shape targets. |
Average Execution Time | Average time spent running queries with the given query shape. |
Execution Count | Total number of times that queries with the given query shape ran. |
Docs Examined:Returned Ratio | Ratio of documents examined to documents returned by queries with the given query shape. |
Manage Report Subscriptions
You can subscribe to or unsubscribe from Query Shape Reports in your project's settings. This setting controls reports for all users in the project. Only users with the Project Owner role can change the subscription, and only Project Owner users receive the reports.
To manage Query Shape Reports:
In Atlas, go to the Project Settings page.
If it's not already displayed, select the organization that contains your desired project from the Organizations menu in the navigation bar.
If it's not already displayed, select your desired project from the Projects menu in the navigation bar.
In the sidebar, click the icon next to Project Overview.
- The Project Settings page
- displays.
Toggle the Query Shape Reports setting.
Turn the toggle on to subscribe or off to unsubscribe. When subscribing for the first time, select the cluster or clusters that you want the report to cover. The change applies to all Project Owner users in the project.
You can also unsubscribe by clicking the unsubscribe link in any Query Shape Report email. The link directs you to Project Settings, where Atlas unsubscribes the project. The unsubscribe link works without requiring you to log in.
Limitations
Query Shape Reports have the following limitations:
The subscription setting applies to the entire project. You cannot subscribe or unsubscribe individual users.
Query Shape Reports are not available through the Atlas Administration API.
Select Query Shapes to Chart
By default, Query Shape Insights displays metric charts for the top five query shapes with the highest Total Execution Time. You can select up to five query shapes to chart in the Query Shape Insights table.
To search for and select query shapes in the Query Shape Insights table:
(Optional) Filter table entries.
You can filter the Query Shape Insights table by the following categories:
Query Shape: In the Search by Query Shape search box, input the query shape or its associated query hash.
Namespace: In the Select Namespaces drop-down menu, select one or more namespaces to filter by.
Command: In the Select Commands drop-down menu, select one or more commands to filter by.
(Optional) Change the sort order.
You can sort the Query Shape Insights table by one or more metric columns to help identify which query shapes to chart.
To sort by a metric in descending or ascending order, click the sort icon next to the associated column name once or twice, respectively. To sort by multiple columns, press Shift and click the sort icons in the order in which you want to multi-sort the table.