Creating Your First Cosmos DB Database

In this article, I will show you how to create your first Cosmos DB database using the Azure portal, and contrast it with a previous article I created on building your first database on the MongoDB Atlas platform. This article assumes that you have an active account with Microsoft Azure and that you are somewhat familiar with navigating the management portal to provision resources.

Create a Virtual Network

In Azure, you need to first create a Virtual Network that allows you to provide specific connectivity rules in your Cosmos DB service. This isn’t necessary for MongoDB Atlas; however, you still have network-level options available including firewall whitelisting rules. In this example, I create a Virtual Network in an existing Resource Group that was previously created, to make it easier to manage them. If you don’t have an existing Resource Group, simply select "Create New" to do so.

Specify a name for the network, and leave the remaining settings to their default values.

Create a new Cosmos DB Service

Next, let’s create a Cosmos DB service. Navigate to your Resource Group, and click on "Add" to bring up the new resource pane; search for Azure Cosmos DB and click on "Create".

Enter a name for the account (which will become the service name) and choose Core (SQL) as the API. Make sure to select the correct location so that the Cosmos DB service runs in the same data center as the network created previously.

In the Network tab, select the Virtual Network you created previously and select the default subnet. To allow testing your connection from your local machine, select "Allow" for your IP Address.

Click "Review + Create" and in the "Review" screen, click on "Create". It will take a few minutes for the service to become available; a screen indicating that the deployment is underway will display the current deployment status.

Create a Container

Let’s create a container which will hold a new database and a collection. Go to the newly created Cosmos DB database and click on New Container. Enter the following information:

Select to create a new database, and name it logdb
Provision the throughput to be shared and use a Throughput value of 400 (minimum)
Enter log for the Container name
Enter /id for the PartitionKey
Click OK

NOTE
You will be charged for this database even if you don’t do anything beyond this point. As a result, make sure to delete the container after you are done with this exercise.

You now have a simple container, with a database and collection. Note that there a few key differences with the MongoDB Atlas service worth noting,

In Azure, you cannot create a “free tier” Cosmos DB database; at the time of this writing, it costs a minimum of $24 per month in the US region.
MongoDB Atlas forces you to use the _id property for the primary key; in Cosmos DB you can specify any JSON property, at any depth.

Add a JSON Document

Finally, let’s add a JSON document to our database. Click on Items just under the log collection and click on the New Item button. The page will allow you to enter a JSON document manually.

{
"id": "a6537b0d-83f8-4968-b4ca-6051ab3cb3c5",
"appname": "sqlserver",
"database": "crm-us",
"datetime": "2019-08-21T18:25:43.511Z",
"text": "user 'sa' logged in",
"priority": "high"
}

You can copy/paste the above JSON document into the Azure portal as shown below.

Click on Save. You will notice that the document will be updated with additional properties that are Cosmos DB specific, including an ETag value and a timestamp. You can also import items into your collection by uploading files that contain a single document or an array of documents.

Key Differences with MongoDB

Without going into a detailed comparison of the platforms, one of the major differences developers should be aware of between MongoDB Atlas and Cosmos DB is that MongoDB uses the BSON format, while Cosmos DB uses the JSON format. While both look similar at first glance, the BSON format extends a few data types that are not supported by JSON. Here is the document created earlier using JSON and BSON for quick reference,

JSON Format	BSON Format
{ "id": "a6537b0d-83f8-4968-b4ca-6051ab3cb3c5", "appname": "sqlserver", "database": "crm-us", "datetime": "2019-08-21T18:25:43.511Z", "text": "user 'sa' logged in", "priority": "high" }	{ "id": ObjectId(“5d5826611c9d440000dd21d1”), "appname": "sqlserver", "database": "crm-us", "datetime": 2019-08-21T18:25:43.511Z, "text": "user 'sa' logged in", "priority": "high" }

Notice that the ObjectId() from the BSON object is not a GUID data type; it is considered to be likely unique and ordered. See MongoDB’s definition of the ObjectId data type here for more information.

The second difference might not be obvious at first: the DateTime property is expressed as a string in JSON surrounded by double-quotes; in BSON there are no double-quotes for a date when entered through the user interface; in reality the date data type in BSON is stored internally as a 64-bit integer that stores milliseconds since the Unix epoch. There are other data types and differences between the two formats; refer to the previous link for more details.

From a conversion standpoint, you should know that you can create an Azure Cosmos DB service that is wire compatible with MongoDB version 3.2 (and 3.4 in preview – see here for details). In this article, we created a Core SQL Cosmos DB service, but it is possible to create a MongoDB compatible data store instead. This means that you can write code that works with MongoDB and point it to Cosmos DB; however, this may not work as intended if your database runs in MongoDB Atlas since the Atlas engine runs on 4.0 and the tested driver version for Atlas is 3.6 (more information here). As a result, the wire compatibility for Cosmos DB seems to only be practical for on-premise deployments of MongoDB; there are a few exceptions as well to consider, such as the $where, $eval and cursor operators, as documented by Microsoft here. There are many other differences between MongoDB and Cosmos DB, but in general, you will find that both platforms are feature-rich.

Back to Cosmos DB, you can now access your collections programmatically using virtually any programming language. The Azure Portal makes it easy to manage your database, create additional collections, and add additional objects such as Stored Procedures, Triggers and User-Defined Functions.