Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 70 ยท Getting started

MongoDB Compass, the Graphical Client

Use MongoDB Compass to connect to a server, browse and edit documents, filter with the query bar, analyze schema, build aggregation pipelines, manage indexes and check validation rules.

The shell is precise and scriptable, but sometimes you want to see your data: browse a collection, click a field, drag a pipeline stage and watch the preview change. MongoDB Compass is the official graphical client for that. It is free, runs on Windows, macOS and Linux, and works with a local server, a self-hosted cluster or Atlas.

This lesson walks through Compass: how to connect, what each tab does, how the query bar works, and when to switch back to mongosh. Compass is a desktop application, so nothing in it can run on this page. The TryIts reproduce two of its features, the query bar (filter, project, sort, limit) and the Schema tab (field types and how often each appears), with a small JavaScript stand-in over sample documents, so you can see the logic behind the screens. They are not MongoDB or Compass.

Compass changes its layout between versions, and some tabs are renamed. The ideas here (connect, query, explain, schema, aggregation, indexes, validation) have stayed the same for years. If a button is not where this lesson says, look for the tab name.

Installing and connecting

Download the installer for your operating system from MongoDB's website (see Installing MongoDB and mongosh for the server side) and run it. On the first screen you enter a connection string such as:

TEXT
mongodb://localhost:27017
mongodb+srv://appUser:[email protected]/shop

Click Connect. For a local server with no authentication, mongodb://localhost:27017 is enough. For a production server, include credentials and the right authSource, or use the form view ("Advanced Connection Options") to fill in hostname, authentication, TLS and SSH tunnel. Compass saves favorite connections, optionally with a color so you never confuse production with test (a red production connection is a cheap safety habit).

After connecting, the left pane lists databases and collections. Selecting a collection opens the tabs below.

The Documents tab and the query bar

The Documents tab lists the collection's documents. You can view them as a list (expandable cards), as JSON, or as a table. Click a field to edit it in place, clone a document, or delete it; every change is a real update on the server, so be careful on shared data.

Above the list, the query bar is the heart of everyday work. It has fields for the same pieces you know from find():

Field Meaning Example
Filter The match document { year: { $gt: 1990 }, genre: "drama" }
Project Fields to include or exclude { title: 1, year: 1, _id: 0 }
Sort Order of results { year: -1 }
Collation, Hint, MaxTimeMS Advanced options under Options { locale: "en", strength: 2 }
Skip, Limit Paging 0, 20

Press Find, and the list shows the first documents that match, with a count and pagination. Compass puts a limit-like guard on very large results so the screen stays responsive. The filter syntax is exactly what you learned in Finding Documents, Comparison Operators and Projection, written as relaxed JSON (keys can be unquoted).

The first TryIt is a stand-in for the query bar: edit the filter, project, sort and limit and press Run. It supports equality, $gt, $gte, $lt, $lte, $in and $or, plus the dot notation you know.

JS A query bar: filter, project, sort, limit

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Explain Plan and Indexes

Two tabs help you tune a query without leaving the window:

  • Explain Plan runs explain for the filter you entered in the query bar and shows the winning plan as a diagram: whether it used an index (IXSCAN) or scanned the whole collection (COLLSCAN), how many documents it examined against how many it returned, and the time. It is the friendliest way to learn how to read explain output.
  • Indexes lists every index with its size and how often it has been used. You can create an index by choosing fields and directions, add options (unique, TTL, partial) and drop an index you no longer need. Unused indexes cost write speed and memory, so the usage column is worth checking now and then. Background on index types is in Index Types.

The Schema tab

MongoDB has no fixed schema, so documents in the same collection can drift apart. The Schema tab samples documents (by default 1,000) and summarizes every field: which types it holds, the share of documents that have it, and a small chart of its values. Numeric fields show a histogram; dates show a timeline; geographic points show a map.

This is how you spot trouble early: a price that is a number in 90% of documents and a string in 10%, a field that only half of the documents contain, or a _id format that changed. The second TryIt computes the same kind of summary for a small, deliberately messy sample.

JS Schema analysis: field types and coverage

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The output flags price (a string slipped in), name (a null), and fields such as tags and added, which only some documents have. Fix such drift with schema validation, covered next.

Validation and Aggregations

The Validation tab shows the collection's validation rules (a $jsonSchema or query-style validator). You can write or edit a rule, choose the validation action (error or warn) and level (strict or moderate), and Compass previews which sample documents would pass or fail before you save it.

The Aggregations tab is a visual pipeline builder. You add stages one at a time ($match, $group, $project, $sort, $lookup...), edit each stage's JSON, and see a preview of the output after that stage on a sample of documents. Seeing the data between stages makes it much easier to debug a long pipeline, and you can:

  • Export the finished pipeline as code for Node.js, Python, Java, C#, Go and more, ready to paste into your application.
  • Save pipelines, toggle stages on and off to see the effect, and run the pipeline with a $out or $merge stage.
  • Ask for the explain plan of the whole aggregation.

A good workflow is to prototype a pipeline in Compass, then copy it into code. Learn the stages in Pipeline Basics first, so you know what the previews mean.

Import, export and the embedded shell

  • Import and export (from the collection's menu) move data as JSON or CSV. Imports can convert field types, and exports can include only the filtered documents. For large or repeatable jobs use mongoimport/mongoexport or mongodump/mongorestore (see Backup and Restore).
  • MongoSH at the bottom of the window is an embedded mongosh. It uses the connection you already opened, so you can switch between clicking and typing.
  • The Performance tab (for servers you may monitor) charts operations per second, slow operations and connections in real time, which is a quick health check.

When to use Compass, and when not to

Use Compass to explore unfamiliar data, to try queries and pipelines, to read explain plans, to check indexes and schema, and to make a one-off edit. Use mongosh or code to repeat a task, because a script can be versioned, reviewed and run again; a series of clicks cannot. Be careful on production: Compass edits are live. Connect with a read-only user for investigation (see Authentication and Authorization), and give each connection a name and color that tells you where you are.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does the Filter field of the Compass query bar contain?

    The filter is the same match document you pass to find().
  2. 2. Which tab shows whether a query used an index or scanned the whole collection?

    Explain Plan runs explain for the current filter and shows IXSCAN or COLLSCAN, with documents examined and returned.
  3. 3. What does the Schema tab do?

    It analyzes a sample so you can spot mixed types and missing fields. Enforcement is done with validation rules.
  4. 4. What is a good safety habit when using Compass with production data?

    Compass changes are live. A read-only user and a visible production color reduce mistakes.
  5. 5. Why prototype an aggregation in Compass?

    Stage-by-stage previews make debugging easy, and you can export the final pipeline for your language.

Summary

  • Compass is MongoDB's free graphical client: connect with a connection string, then browse databases, collections and documents.
  • The query bar maps to find(): filter, project, sort, skip and limit, plus options such as collation and maxTimeMS.
  • Explain Plan, Indexes, Schema and Validation help you tune and check a collection; the Aggregations tab previews each pipeline stage and exports code.
  • Import/export and an embedded mongosh are built in; use scripts for repeatable work and read-only connections for investigation.

Next, learn how the shell and Compass see your data in Documents and JSON.