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
-
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.
-
Click into a complex field (nested document, array of subdocuments). Compass drills in and analyzes the sub-structure.
-
Use the Documents tab with filter queries to inspect outliers. The filter input takes the same JSON syntax as
find().
Diagnose a slow query
-
Paste the query into the Documents filter. Switch to the Explain Plan tab; click Execute Explain.
-
Look at the tree visualization. A
COLLSCANroot means no index; anIXSCANshows the index name and the bounds.docsExaminedvsnReturnedis the over-fetch ratio. -
From the Indexes tab, see existing indexes and their usage.
accesses.opsper index reveals whether the index is being used. -
Create a candidate index from the Indexes tab. Compass writes the
createIndexcall and shows progress.
Build an aggregation pipeline
-
Open the Aggregations tab. Each stage is a card; the right pane shows a preview of the documents flowing out of that stage.
-
Add stages incrementally. Start with
$match, see the preview shrink, add$projector$group, see the shape change. -
Click Explain on the pipeline. Compass shows the executed plan with timings per stage.
-
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
-
Open the Performance tab on the database root. Real-time charts of operations/second, network, memory, and slow queries.
-
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
$sampleupstream. Stages that depend on the full result set ($groupover 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.