The author selected the Open Internet/Free Speech Fund to receive a donation as part of the Write for DOnations program. Show IntroductionThe MongoDB shell allows you to access a database as long as you already have access to the server on which MongoDB is running. However, a command line interface isn’t always ideal for working with a database, as it may not be clear how one can find or analyze their data. Some may find it helpful to instead use a visual tool to view, manipulate, and analyze their data. To this end, the MongoDB project offers an official graphical user interface called MongoDB Compass. With MongoDB Compass, sometimes shortened to Compass, you can access most of the features the MongoDB database engine offers through an intuitive visual display. You can glance through databases, collections and individual documents, interactively create queries, manipulate existing documents, and design aggregation pipelines through a dedicated interface. In this tutorial, you’ll install MongoDB Compass on a local machine and familiarize yourself with how to perform various database administration using the graphical tool. PrerequisitesTo follow this tutorial, you will need:
Note: The linked tutorials on how to configure your server, install, and then secure MongoDB installation refer to Ubuntu 20.04. This tutorial concentrates on MongoDB itself, not the underlying operating system. It will generally work with any MongoDB installation regardless of the operating system as long as authentication has been enabled and you’ve allowed access to it from your local machine. Step 1 — Installing MongoDB CompassTo use MongoDB Compass, you must install it on your local computer. MongoDB provides official packages for the graphical tool for Ubuntu and RHEL-based Linux distributions, as well as Windows and MacOS. To find the appropriate package for your system, navigate to the MongoDB Compass Downloads page in your web browser. There, find the Available Downloads section on the right-hand side of the page and select your desired Version and Platform from the drop-down menus there. This tutorial’s examples will install version 1.28.4, the latest stable version at the time of this writing. After making your choices, click the
Copy Link button which will copy the download link to your clipboard. If you selected Ubuntu as your platform this link will download a Then, open up a terminal session on your local machine. If your local machine is running Ubuntu and the link you copied is for a
Then install the
This command will install the Compass package along with all necessary dependencies. If, however, you’re using a RHEL-based distribution like CentOS, Fedora, or Rocky Linux, you can download and install the
Note: MongoDB Compass is also available for Mac and Windows systems. To set up MongoDB Compass on non-Linux systems, follow the installation instructions from the official MongoDB Compass documentation. After installing the MongoDB Compass package, you can run the installed software by executing:
Compass will greet you with a welcome screen: Now that you’ve installed MongoDB Compass on your local machine, you can connect it to the MongoDB instance running on your remote server. Step 2 — Connecting to The MongoDB ServerTo use MongoDB Compass with the MongoDB instance running on your remote server, you must first connect to it like you would if you were accessing the database through the shell. Assuming you completed the prerequisite tutorial on How To Configure Remote Access for MongoDB on Ubuntu 20.04, you will have already configured your MongoDB server to allow remote connections from your local machine. Compass allows you to connect using either a connection string — a single line of text containing all necessary database connection information — or by filling in all the connection details individually. This guide will outline how to connect using the second option, but if you’d like to learn how to construct a connection string we encourage you to check out the official documentation on the subject. Click Fill in connection fields individually at the top of the welcome screen. The New Connection screen will appear with a list of empty fields: Enter the IP address of the remote server on which your MongoDB instance is running into the Hostname field. Leave the default Port value unless you’ve changed the port on which your MongoDB instance is listening for connections. Because the server was secured with authentication enabled, you also need to switch the Authentication option to Username / Password. After selecting this option, enter your administrative MongoDB user’s username, the password associated with this account, and this user’s authentication database in the three new fields. After clicking the Connect button, Compass will attempt to connect to the MongoDB instance. If it succeeds, you’ll be taken to the Home screen showing the list of all the databases on the instance. They will also appear in the left panel along with high-level information like the database server’s IP address and what version of MongoDB it’s running: If the connection attempt fails, make sure that you entered all the connection details correctly. Once you’ve successfully connected your local Compass installation to your remote MongoDB server instance you can move on to creating a new test database and inserting test data into a new collection. Step 3 — Preparing the Test DataTo illustrate the different features of MongoDB Compass, this guide will use a set of sample documents in its examples. This step involves creating a collection and inserting this set of sample data into it. This sample collection contains documents representing the twenty most populated cities in the world. A sample document for Tokyo will follow this structure: Example document representing Tokyo
The document contains information about the city’s name, the country where it’s located, the continent, and its population represented in millions. This guide will name the sample database To begin, click the CREATE DATABASE button at the top of the Home screen. Alternatively, you can click the plus sign (+) at the bottom of the left panel. In MongoDB, a database and collection are usually created when the first document is inserted into the collection without any need for an explicit creation operation for these structures. However, it is possible to create a new database explicitly and that’s how you’ll do it in MongoDB Compass in this tutorial. Type Compass will create the database. Click the Now that the database and collection have been created, you can insert a list of unsorted documents into the A window will appear in which you can enter one or more data documents, in JSON format, as you would do when using the shell command. Enter the following set of documents into the field, replacing any content that was there by default:
Click the INSERT button, and Compass will insert the list of documents and then automatically display them in the collection browser: With that, you’ve successfully created a set of sample documents representing the world’s most populated cities. This collection will serve as this guide’s example data as you explore MongoDB Compass. Next, you’ll learn how to browse data with the graphical interface. Step 4 — Navigating and Filtering the DataMongoDB Compass is a convenient tool for browsing through the data stored in a MongoDB database through a graphical interface. It removes the burden of having to remember the names of obscure databases or collections, and you can navigate to any database or collection on your MongoDB server with just a few clicks. The primary navigation tool in Compass is the left panel, which works like a tree showing the database’s contents. The top-level nodes are the databases, which you can click on to reveal the list of available collections. To navigate to the By default, Compass will show the first 20 unfiltered results returned by an empty query on the selected collection. To the right off the ADD DATA button you used in the previous step, you’ll find a View section with three separate display modes you can choose from:
Regardless of what view you use, you can use the data browser screen to quickly query
your data just like you would with the
In this Go ahead and enter this query document into the FILTER field, and then press FIND:
MongoDB Compass will narrow the list of documents to the two entries matching the filtering
criteria. You can use any valid query document that you would use in a You can also sort the results and apply projections to return only a limited subset of fields using the data browser interface. Click on the OPTIONS button near the filtering query bar to reveal further options. The PROJECT and SORT fields will appear below the FILTER field. A number of other fields will also appear, but it would be beyond the scope of this guide to discuss all of them in detail. Both the PROJECT and SORT fields accept the same documents you would pass to the To limit the list of fields to
To sort the list by population in ascending order, add the following sort document to the SORT field:
Click the FIND button again to apply these projection and sorting documents: Compass now shows two simplified documents representing New York and Mexico City. The results are equivalent to running the following query in the MongoDB shell:
Just like with filter query documents, syntax errors in the projection and sorting settings will cause the respective field’s label to turn red, making it easier to spot when there’s an issue. To clear the filter, projection, and sort documents you’ve applied, you can click the RESET button. Note: Using the data browser, you can also modify an individual document’s contents. From the List view, hover your cursor over a document in the list and clicking on the pencil icon within the contextual menu that appears: The static display will change into the list of editable fields that you can freely modify to quickly alter the document: After making your desired changes, click the UPDATE button and they will be written to the database. Step 5 — Using the Interactive Aggregation Pipeline BuilderCompass’s aggregation pipeline builder is a graphical tool aiding with the creation of multi-step aggregation pipelines. This step explains how to build a pipeline by adding sequential aggregation stages. Note: The example in this step follows the aggregation pipeline from the How to Use Aggregations tutorial that uses similar test data. If you are not familiar with aggregation pipelines, you can follow that tutorial to learn about their principles first. As an example, say that the task at hand is to list the most populated cities of countries represented in the collection, but only those found in Asia and North America. The pipeline should only return the cities’ names and populations. The results should be sorted in descending order by population, returning countries with the largest cities first. Lastly, the documents’ structure should replicate the following: Example document structure
To start building an aggregation pipeline that will satisfy these requirements, open up the Aggregations tab for the Begin by filtering the initial
documents coming from the The top section of the aggregation pipeline builder view shows the source documents in the collection. This allows you to quickly glance through the documents that will be used as input for the aggregation pipeline. Note that if the documents don’t immediately appear, you may need to press the refresh button (⟳) to make these documents appear if they aren’t there by default. In the case of this example these are the The first step to building this example pipeline is to filter the initial documents coming
from the Enter the following to match only cities from North America and Asia:
Compass will automatically preview the results of applying the first stage, displaying the filtered documents on the right. This way, you can quickly verify that each stage works as intended: The second step is to order the documents by population in descending order. Add an additional stage using the ADD STAGE button. Another
empty stage row will appear. There, select the
Once again, returned documents will have the same structure, but Tokyo comes first in the preview pane that now shows the sorted results instead: Since the list of cities is now sorted by the population coming from
the expected continents, the next necessary step is to group cities by their countries, choosing only the most populated city from each group. Add another stage, this time selecting To group cities by unique continent and country pairs and summarize these pairs by only showing the name and population of their most populated cities, enter the following grouping settings:
The After applying the grouping stage, the list of documents is reduced to 9 entries, but the document structure is now different than before.
Compass previews the output from the group stage on the right, showing the newly computed The last step to satisfying the requirements described at the beginning of this section is to transform the document’s structure. You can do that by adding another stage row and selecting
This
document first suppresses the Notice that the preview pane on the right for this aggregation stage shows the sample output after transformation. With this, you can quickly confirm the projection stage resulted in the expected transformation. By using the aggregation pipeline builder, you can conveniently build aggregations stage by stage without worrying about the complex syntax of a single aggregation command. Toggling on the SAMPLE MODE switch ensures that MongoDB Compass will use only a subset of input documents, which makes it quicker to develop pipelines when the source data set is large. Thanks to the preview pane for each of the stages, you can verify that each stage provides expected results. You can also disable and enable individual stages with the flip-switches to understand how the aggregation pipeline will work without some of the stages activated. Step 6 — Analyzing the Schema StructureIn previous steps, you used MongoDB Compass to browse through data using interactive tools. With these examples Compass served as more of an aid for performing routine functions in MongoDB, but in this step you’ll explore a feature that’s unique to Compass: its schema visualizer interface. This tool can help you understand the structure of data within your collections. To use it, first select the Schema tab in the Note: Similarly to just browsing the data, you can use filter query documents to narrow down the selection and force MongoDB Compass to provide insights on a subset of collection documents: For each of the document fields, the schema visualizer will provide insights into the data found in the database. For instance, notice the For the The By combining Compass’s schema visualizer with MongoDB’s filtering capabilities you can quickly scan your data and the generated visualizations, allowing you to analyze your data without having to write out complex queries. This comes in handy not only to visualize the contents of the database, but also to understand the data to aid decisions about creating indexes or sharded clusters. ConclusionIn this article, you familiarized yourself with MongoDB Compass, a GUI that allows you to manage your MongoDB data through a convenient visual display. You used the tool to create a new collection, insert new documents, filter and navigate the data, create a multi-stage aggregation pipeline, and visualize the collection’s schema using the schema visualization tool. The tutorial described only a subset of MongoDB Compass features, which encompass many other capabilities related to MongoDB administration, such as index management, query execution plan visualization, and a view of the server’s real-time performance metrics. To learn more about how Compass can help you, we encourage you to study the official official MongoDB Compass documentation. |