App Environment MongoDB Query Analysis API
The MongoDB Query Analysis API reads the profiler of a MongoDB database managed by Quave ONE and tells you which queries cost the most time, which ones scan too many documents per document returned, which ones run most often, how large each collection and index is, and which indexes are missing or unused.
It connects with a platform user that is denied reads and writes on your collections, and it only runs profiler and metadata commands (system.profile aggregation, $indexStats, $collStats); it never changes your profiler settings and never reads system databases such as local. Every value in a query is replaced by its type before it is returned, for example {"email": "<string>"}. Key segments that look like ids become <id>, and keys that look like data (emails, phone or document numbers, tokens, free text, very long keys) become <key>. The response contains query shapes, not your data.
Make sure to read the Get Started document to understand how the API works.
Note: These endpoints accept only user tokens (not environment tokens). They work only for MongoDB databases managed by Quave ONE. External MongoDB (for example Atlas) is not supported.
How the profiler is configured
Managed MongoDB databases record operations slower than 100 ms (profiler level 1, slowOp) in a 1 MB system.profile, set in the database server configuration. You do not need to enable anything. Cheap but inefficient or very frequent queries stay below that threshold. To see them, lower the threshold for a while with your own admin user (the DB_USER_ADMIN of the environment), generate traffic, analyze, and set it back:
// in mongosh, connected as your admin user
db.getSiblingDB('<your database>').setProfilingLevel(1, { slowms: 20 });
// ... run the analysis with sortBy=docsExaminedRatio and sortBy=count ...
db.getSiblingDB('<your database>').setProfilingLevel(1, { slowms: 100 });
A low threshold adds load and fills the 1 MB system.profile quickly on a busy database; the analysis reads whatever is still recorded. The platform user cannot change these settings.
The profiler records operations on the member that runs them. The analysis reads the primary, so reads routed to secondaries are not included. Index usage ($indexStats) is also per member and resets when the member restarts.
Analyze MongoDB queries
Send a GET request to /api/public/v1/app-env/mongodb/query-analysis.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
appEnvId | String | Either/or | The ID of the MongoDB app environment. |
envName | String | Either/or | The CLI environment name (alternative to appEnvId). |
dbName | String | No | Database to analyze. Default: the DB_NAME env var, otherwise the (up to 10) user databases with the most profiler entries in the window. The others are listed in skippedDatabases. System databases (admin, local, config) are rejected. |
collection | String | No | Only analyze operations on this collection. |
fromMinutes | Number | No | Look back this many minutes. Default: 60. Max: 10080 (7 days). |
slowerThanMs | Number | No | Only operations at least this slow. Default: 0 (everything recorded). |
limit | Number | No | Max query shapes per database. Default: 20. Max: 100. |
sortBy | String | No | Ranking of query shapes: totalMillis (default), docsExaminedRatio (documents examined per document returned), docsExamined or count. With little traffic, total time hides inefficient shapes; docsExaminedRatio shows them. |
includeChangeStreams | Boolean | No | Include change-stream reads (for example Meteor reactivity, getmore with an empty filter) in queryShapes. Default: false. They are always counted per collection in changeStreamReads. |
includeIndexes | Boolean | No | Read index usage, index sizes and collection sizes. Default: true. |
indexScope | String | No | findings (default): collections with a finding, up to 20. database: every collection of the analyzed database, up to 300, even when the profiler recorded nothing. |
Response
| Field | Description |
|---|---|
databases[] | One entry per analyzed database: dbName, profiler (level, slowMs, sampleRate), entriesAnalyzed (every profiler entry in the window; they are summarized on the server, not sampled), truncated (more than 5,000 distinct groups; the least relevant by sortBy were dropped), changeStreamReads (ns, count, totalMillis) and queryShapes. |
queryShapes[] | Operations grouped by namespace, operation, plan and redacted query shape, sorted by sortBy. Each has count, totalMillis, avgMillis, maxMillis, totalDocsExamined, totalReturned, docsExaminedRatio, avgDocsExamined, avgKeysExamined, avgReturned, planSummaries, queryHashes, lastSeen, findings and, when there is a finding, suggestedIndex. |
indexFindings[] | For each reviewed collection: collection (count, sizeBytes, storageSizeBytes, totalIndexSizeBytes), its indexes (name, key, ops, since, sizeBytes, and constraint: unique or ttl when the index enforces one), unusedIndexes (no query access since the index stats were reset on that member, usually its last restart, with host and sizeBytes; unique and TTL indexes are never listed because they still work on writes) and suggestions with the existingIndex that already covers a suggestion, if any. |
indexSummary | Totals of the review: collections, indexes, unusedIndexes, unusedIndexSizeBytes, statsSince (oldest index stats reset) and truncated. |
skippedDatabases[] | Without dbName and DB_NAME: databases not analyzed, with their profiler entries. Sample datasets (sample_*) are only analyzed when no other database exists, and when the profiler recorded nothing anywhere, the largest database is analyzed. |
findings can contain:
COLLSCAN: the query read the whole collection because no index matched.DOCS_EXAMINED_MUCH_HIGHER_THAN_RETURNED: at least 100 documents were read per document returned (over at least 1000 documents).IN_MEMORY_SORT: the sort was done in memory instead of using an index.
suggestedIndex follows the Equality, Sort, Range rule: equality fields first, then sort fields, then range fields. Check a suggestion against your workload before you create the index.
Example
curl -H "Authorization: $QUAVE_ONE_TOKEN" \
"https://api.quave.cloud/api/public/v1/app-env/mongodb/query-analysis?envName=my-mongo-production&fromMinutes=120"
{
"databases": [
{
"dbName": "shop",
"profiler": { "level": 1, "slowMs": 100, "sampleRate": 1 },
"entriesAnalyzed": 42,
"truncated": false,
"queryShapes": [
{
"ns": "shop.orders",
"op": "query",
"shape": {
"filter": { "customerId": "<string>", "createdAt": { "$gte": "<date>" } },
"sort": { "createdAt": -1 }
},
"count": 37,
"avgMillis": 412,
"avgDocsExamined": 180000,
"avgReturned": 20,
"planSummaries": ["COLLSCAN"],
"findings": ["COLLSCAN", "DOCS_EXAMINED_MUCH_HIGHER_THAN_RETURNED"],
"suggestedIndex": { "customerId": 1, "createdAt": -1 }
}
]
}
],
"indexFindings": [
{
"ns": "shop.orders",
"unusedIndexes": [{ "name": "legacyStatus_1", "key": { "legacyStatus": 1 } }],
"suggestions": [{ "suggestedIndex": { "customerId": 1, "createdAt": -1 } }]
}
]
}
Slow Queries tab
The Slow Queries tab of a MongoDB environment uses the same platform user and the same redaction, so it shows query shapes without your data.