Skip to content

MongoDB Compass for debugging: schema, explain, and query analysis

Use MongoDB Compass to inspect schemas, run explain plans visually, profile slow queries, and validate aggregation pipelines without typing them.

MongoDB Compass is the official GUI client — a desktop app for connecting to any mongod/mongos/Atlas cluster and inspecting data, schemas, indexes, and query plans. It is not the only client (Studio 3T, Robo 3T, JetBrains DataGrip, mongosh itself) but it is the one with the deepest first-party integration: aggregation pipeline builder with stage-by-stage previews, schema analysis that samples documents to infer field types, and an explain view that renders the plan tree visually instead of as nested JSON. This article covers the debugging workflows where Compass replaces a dozen mongosh commands.

How to verify

Confirm Compass connects and the connection’s user has the required privileges:

# from a terminal on the same machine
ping -c 1 mongo.example.internal
openssl s_client -connect mongo.example.internal:27017 -servername mongo.example.internal </dev/null 2>/dev/null | head -5
# from Compass: File > New Connection
# paste: mongodb+srv://debug-user:secret@cluster.example.internal/?authSource=admin

A successful connection lands on the databases tab. If you see only a subset of databases, the user’s roles do not cover the others — mongosh and db.runCommand({ usersInfo: "debug-user" }) will tell you which roles you have.

What’s happening

Compass is an Electron app wrapping the Node.js MongoDB driver. Every action you take in the UI executes a corresponding driver call against the cluster you connected to. The schema-analysis feature samples 1000 random documents from a collection ($sample aggregation stage) and tallies field paths, types, and value distributions. The explain view runs explain("executionStats") on the current query and parses the output into the tree visualization. The aggregation builder uses $sample again to preview the output of each stage on a small subset.

This sampling matters: Compass schema analysis describes the structure of 1000 random docs, not the entire collection. A field that exists on 0.1% of documents may not appear at all; a field with rare type variations will show only the common types. Treat Compass schema analysis as a starting hypothesis, not a contract.

The procedure

Inspect an unfamiliar collection

  1. Open the collection and click the Schema tab. Compass samples and renders field paths with type breakdowns. For string fields with low cardinality, it shows the top value distribution.

  2. Click into a complex field (nested document, array of subdocuments). Compass drills in and analyzes the sub-structure.

  3. Use the Documents tab with filter queries to inspect outliers. The filter input takes the same JSON syntax as find().

Diagnose a slow query

  1. Paste the query into the Documents filter. Switch to the Explain Plan tab; click Execute Explain.

  2. Look at the tree visualization. A COLLSCAN root means no index; an IXSCAN shows the index name and the bounds. docsExamined vs nReturned is the over-fetch ratio.

  3. From the Indexes tab, see existing indexes and their usage. accesses.ops per index reveals whether the index is being used.

  4. Create a candidate index from the Indexes tab. Compass writes the createIndex call and shows progress.

Build an aggregation pipeline

  1. Open the Aggregations tab. Each stage is a card; the right pane shows a preview of the documents flowing out of that stage.

  2. Add stages incrementally. Start with $match, see the preview shrink, add $project or $group, see the shape change.

  3. Click Explain on the pipeline. Compass shows the executed plan with timings per stage.

  4. Export to language. Compass generates Node.js, Python, Java, C#, Ruby, Go, PHP, or Rust code that reproduces the pipeline — copy into the application.

Live performance view

  1. Open the Performance tab on the database root. Real-time charts of operations/second, network, memory, and slow queries.

  2. Use the slow-query log to capture currently-running operations exceeding a threshold.

Operational notes

  • Compass uses driver-side options. readPreference, readConcern, writeConcern, and the connection’s user roles all apply. A read-only user cannot create indexes from the UI.
  • The schema analysis is sampled. Field absence in the sample does not mean field absence in the collection. Validate with explicit queries before refactoring.
  • The aggregation preview uses $sample upstream. Stages that depend on the full result set ($group over the whole collection) show approximations, not the real output.
  • Compass connects over the same network as mongosh. If your cluster is behind a VPN or private endpoint, the same network requirements apply.
  • The Free Text Search analyzer is not visible in Compass. Text-index analysis happens server-side; Compass shows the index existence but not the tokenization.
  • Compass logs to a local file. ~/Library/Logs/MongoDB Compass/ on macOS, %AppData%\MongoDB Compass\logs\ on Windows. Useful for support requests, less useful for normal operation.

Stack Harbor uses Compass as the day-one diagnostic tool for new client engagements — schema discovery, slow-query triage, and index audit before any change is made. It is a faster path to a mental model than reading the application source. For ongoing tuning, we pair Compass-based exploration with mongosh automation and the $indexStats aggregation. See /en/services/managed-operations/ for the engagement model.