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, 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 index-metadata commands (system.profile, $indexStats); it 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), set in the database server configuration. You do not need to enable anything. The platform user can read the profiler but cannot change its level or threshold.

The profiler records operations on the member that runs them. The analysis reads the primary, so reads routed to secondaries are not included.

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.
includeIndexes	Boolean	No	Read index definitions and usage for collections with findings. Default: true.

Response

Field	Description
databases[]	One entry per analyzed database: dbName, profiler (level, slowMs, sampleRate), entriesAnalyzed, truncated, and queryShapes.
queryShapes[]	Operations grouped by namespace, operation and redacted query shape, sorted by total time. Each has count, totalMillis, avgMillis, maxMillis, avgDocsExamined, avgKeysExamined, avgReturned, planSummaries, queryHashes, lastSeen, findings and, when there is a finding, suggestedIndex.
indexFindings[]	For each collection with a finding: its indexes (with constraint: unique or ttl when the index enforces one), unusedIndexes (no query access since the index stats were reset, usually the last restart; 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.

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.