Cosmos DB diagram

Cosmos DB & MongoDB API

In this article we will show how to connect to Cosmos DB (API for MongoDB) and how to visualize an existing database structure.

What is Cosmos DB API for MongoDB?

Azure Cosmos DB API for MongoDB allows you to use Cosmos DB in a way as if it were a MongoDB database. This way you can leverage your experience working with MongoDB, as well as use your favorite drivers and other tools. In case you have been working with Moon Modeler to create structures for MongoDB, you can go ahead and focus on working with Cosmos DB API for MongoDB. For more information about Cosmos DB, please visit

Sample MongoDB structure created in Cosmos DB

For the purpose of this article, we have created a simple database with a single collection in Azure Cosmos DB. If you are new to Cosmos DB, you can see in the following image where you can easily view your existing data in Azure.

Cosmos DB API for MongoDB - sample

The data explorer (1) shows the sample database (2) and the collection person (3). Since there can be many different records, it’s a good idea to choose one that represents the data structure well. You can use filters for this purpose, as seen above the JSON record (4). The record itself is then displayed including formatting (5) and provides a degree of visualization.

However, if the structure of the database, collections, documents and other objects is more extensive, it is a good idea to visualize everything in a diagram, for example. Moon Modeler offers this option. With this tool you can create ERD-like diagrams, add notes and other graphical elements, etc.

Creating a Cosmos DB database connection


In order to create a database connection in Moon Modeler, you will need database credentials. Where to find them and what information will be needed?

  • URL (server/host)
  • Port
  • User name
  • Password

This figure shows where to find this information in the Azure area.

Credentials in Azure

Click on Quick start and the Others tab. The Host, Port, Username, and Primary password will be displayed. This is exactly the information we will use in Moon Modeler.

Moon modeler

To create a new connection to the Cosmos DB API for MongoDB, click the Connections button and then click Create new connection. Enter a name for the connection and enter the Azure data in the URL field, in the form Host:Port.

Cosmos DB for MongoDB - connection

Then go to the Authentication tab, select the SCRAM-SHA-256 type, and enter a User name and Password.

authentication for MongoDB API for  cosmos db

We’re almost finished. Now it’s important to enable TLS. So go to the TLS tab and just enable this option.

TLS enabled

Now you can go back to the first tab. If you don’t know the name of the database and didn’t fill in this value directly, click on Load databases. A list of available databases will load and you can conveniently select the one you want to visualize with the drop-down element. Then select the database and save the connection settings.

connection settings

Reverse engineering

A new database connection is created. Now just click on the Connect and load existing database structure link.

Load existing Cosmos DB structure.

Moon Modeler will load the information from the database and create the project including the diagram. Example of the newly created project with labels added:

Cosmos DB diagram

Editing connection properties

If you need to optimize the speed of reverse engineering, or if you have data without references in the structure, you can change the database connection settings and run reverse engineering again.

Editing database connection

Additional settings:

Cosmos DB connection properties

For more information visit page Database connections

Creating documentation for Cosmos DB

Once you have successfully created a project, you can add logical information to it, such as labels, set captions to references, specify estimated sizes, and add other important information to the project that is useful to document or use when communicating with others. You can generate an interactive HTML report for these purposes, or export the diagram to PDF.

Forward engineering and script generation

Another option you have is to generate validation scripts for your Cosmos DB schema design. In the image below, you can see the script generated for the project loaded from the Azure Cosmos DB API for MongoDB.

Script generated for CosmosDB API for MongoDB

Get started today and try Moon Modeler