Prashanth Jayaram

Getting Started with Azure Cosmos DB and MongoDB API

November 7, 2018 by

In the previous article on Azure Cosmos DB, we reviewed NoSQL concepts and how to integrate with the Microsoft Azure platform-as-a-service model using the API. After working as a database engineer for over a decade, I feel that this technology is the future for many organizations for various reasons. I had that in mind as I wrote this article which will provide basic information and help you to get started with MongoDB API integration. The MongoDB API works with BSON documents. BSON is MongoDB’s binary-encoded-version of JSON, and it extends the JSON model with additional language feature support. It’s a great effort from Microsoft to build the enterprise solutions which provide flexibility in manage distributed data along with scalable option.

A quick overview

  1. Azure Cosmos DB is a derived version of Azure DocumentDB
  2. Its launched with Microsoft build in May 2017
  3. It’s a globally distributed multi-model database PaaS model
  4. The data is globally distributed with automatic index tuning is enabled by default
  5. Enterprise features include: 
    1. Globally distributed
    2. Automatic sharding
    3. Availability and latency guaranteed
    4. Automatic indexing tuning
    5. Encryption
    6. Backups

Let’s deep dive into the this Microsoft Azure PaaS (platform-as-a-service ) offering and see how it can be beneficial for us. This article covers the following topics:

  1. Introduction
  2. Setting up
  3. Creating a database and collection
  4. MongoDB query samples
  5. And more…

Quick overview

Azure Cosmos DB is a globally distributed, replicated, multi-model database service that offers 99.99% availability within the region. It also offers rich querying over schema-free data, helps to deliver configurable and reliable performance, and enables rapid development.

Azure Cosmos DB is a right choice for many or new web, mobile, gaming, and IoT applications where automatic scaling, predictable performance, high availability, high throughput, rich indexing, and provide a platform for rapid application building process and rich capability to query over schema-free data are the key requirements.


Azure Cosmos DB is a complete service and ready to use: It gives you a complete product and can be automatically replicated in data centers worldwide using local and global distribution. Partitioning provides elastic scaling and its automatic, the resource partition is first spread across the regions using a local distribution layer and the resource partitions are replicated across global regions using global distribution.

Getting started

Let’s pop into the demo, and create a new account.

This section details the step required to create and configure Azure Cosmos DB.

  1. Log in to the Azure portal
  2. On the left part of the screen, click the New button and type the search string Cosmos to lookup for Azure Cosmos DB

  3. In the New account form, enter the required configuration for the new account.

    Four programming models are supported:

    • Key-Value
    • Column family
    • Documents
    • Graph

    In this section, we’ll walk-through the steps to integrate MongoDB API. Let us choose MongoDB API and type in other values of the form. The following table takes you through the required information to fill out the values needed for the MongoDB API integration


    Suggested value



    Unique value

    A unique name you choose to identify the new account. is appended to the ID you provide to create your URI, so use a unique but identifiable ID. The ID may contain only lowercase letters, numbers, and the ‘-‘ character, and must be between 3 and 50 characters.



    The API determines the type of account to create. Five APIs exist to suit the needs of your application: SQL (document database), Gremlin (graph database), MongoDB (document database), Azure Table, and Cassandra, each which currently require a separate account. 

    Select MongoDB because in this quick start you are creating a document database that is queryable using MongoDB.

    Learn more about the MongoDB API


    Your subscription

    The Azure subscription that you want to use for the new account

    Resource Group

    The same value as ID

    The new resource group name for your account. For simplicity, you can use the same name as your ID.


    The region closest to your users

    The geographic location in which to host your Azure Cosmos DB account. Choose the location closest to your users to give them the fastest access to the data.

  4. Click Create to create the account.

  5. Extensible Multi-APIs

    The database is first stored locally. This is our local distribution level. In this case, it happens to be in the region of US East. The databases are then replicated to other regions. This always ensures that the database is available and easily accessible. The extensible APIs that you can use include .NET, .NET Core, Node.js, Java, Python, and MongoDB. If you’re using .NET, you can use DocumentDB API, MongoDB API, Graph API, or Table API. Java and Node.js will only work with the Document DB APIs, MongoDB APIs, and Graph APIs. Python will only work with the DocumentDB API, and Gremlin, only the Graph API.

  6. Enable geo-redundancy

    In this case, the Geo-Redundancy and Multi-region writes are disabled. For the demo, I will be going with the default setting. But, let us take a moment to discuss partitioning, which provides elastic scaling for Azure Cosmos DB. First, we have our local distribution layer. Here, the resource partitions are spread across the region. And then we have a global distribution layer, now our resource partitions are replicated. And the best part of this is, it’s all handled automatically

    It uses five different phases of consistency levels: bounded staleness, strong, session, eventual, and consistent-prefix and it provides a guaranteed latency of less than 10 milliseconds for data read and less than 15 milliseconds for data write operations.

  7. A Request unit (RU) is the measure of the throughput. It also ensures predictable performance no matter how demanding the workload the application places on the database. The operation in Azure Cosmos DB has a deterministic RU value and it is directly based on the throughput required to complete the process. You can compare throughput to throughput currency as it allows you to specify the throughput level that is required to complete the operation. This way you don’t need to really worry about provisioning any hardware. This gives us an insight into selecting and defining the required RU. Every operation such as reads, writes, SQL Query and Stored Procedure execution have a deterministic RU. For example, the write operation will always cost more than reads, and running a query on data over an indexed data set will always cost less than querying over data that are not indexed. For every operation, Azure Cosmos DB has a way to compute and let us know exactly how many RUs that the request got consumed and was charged. RUs are really a very simple way to manage and ensure predictable performance.

  8. On the toolbar, click Notifications to monitor the deployment process. When the deployment is complete, open the new account from the All Resources tile.

Get Started with MongoDB

Lets us go ahead and create some data, and the first step is to create a container for the data. Each of the APIs has a different term for the container. Microsoft Azure Cosmos DB MongoDB API comes with in-built comprehensive support for MongoDB query language constructs. The following are the few samples to understand how to use MongoDB query. You can find a more detailed list in the here

Let me expand the collection and click on documents. In the portal, it display as documents in the collection. The following sample document created is used for the demonstration

To create a new document, Click New Document, type in the document with key-and-value pair data and click Save. Repeat the steps to enter the other pair of document in the fruits collection.

 “id”: “Strawberry”,
 “Qty”: “13”,

In the next query windows, type in {}, and click Execute Selection to get all the documents of the collection

The following example selects the specific “Apples” document from the fruits collection


The following example uses $in operator to compare more than one value from the fruits collection. In this case, the documents with the value Apples and Oranges are listed.

{“id”:{$in: [“Apples”,”Oranges”]}}

The following example $or is used to retrieve the documents that satisfies the logical condition using $lt operator and id value which is equal to bananas are listed.

{ $or: [ {qty: { $lt:15 } },{“id”:”bananas”} ] }

The following example is a regular expression used to retrieve the documents that start with word App.

{ “id”: {$regex: “^App”}}

The following example is a regular expression used to retrieve the documents that end with word nas.

{ “id”: {$regex: “nas$”}}

The following example shows how to update the document. To update the document, use the Edit Filter option and type in the condition clause to retrieve the specific document and modify the fields and click Update button to save the changes.

The following example shows how to delete the document. To delete the document, use the Edit Filter option and type in the condition clause to retrieve the specific document and click Delete to reflect the changes.

That’s all for now…


Thus far, we’ve taken a walkthrough of MongoDB API integration with Azure Cosmos DB. We started with introduction, definition, and configuration. Then we explored the multi API, multi-model capabilities, MongoDB APIs integration. In my next article, I will discuss more on MongoDB migration and other details. I hope you enjoyed reading this article. Feel free to provide feedback or questions in the comments below

Prashanth Jayaram
SQL Azure

About Prashanth Jayaram

I’m a Database technologist having 11+ years of rich, hands-on experience on Database technologies. I am Microsoft Certified Professional and backed with a Degree in Master of Computer Application. My specialty lies in designing & implementing High availability solutions and cross-platform DB Migration. The technologies currently working on are SQL Server, PowerShell, Oracle and MongoDB. View all posts by Prashanth Jayaram