Azure Cosmos DB's MongoDB API, Briefly

Azure has two services your MongoDB code can talk to, Azure Cosmos DB for MongoDB, billed in request units, and Azure DocumentDB, billed by its servers, and moving to either is often a new connection string plus a careful check of what each one doesn't support.

Journeyman · MongoDB · Cosmos DB · Updated

By

After this lesson you can

  • Explain what Azure Cosmos DB for MongoDB and Azure DocumentDB are, and what changes for an app's code when it moves to one
  • Name what differs on Azure Cosmos DB for MongoDB, from request units and rate limits to unsupported features, and what costs money

Key takeaways

  • Azure Cosmos DB for MongoDB and Azure DocumentDB speak MongoDB's wire protocol, so the drivers, mongosh and Compass connect to them, but neither runs MongoDB's own server.
  • Moving an app to one is often a new connection string, then a test of every query, because each supports most of MongoDB but not all of it.
  • Cosmos DB for MongoDB measures work in request units. Over the budget you set, requests are refused with error 16500 until you retry or pay for more.
  • On Cosmos DB for MongoDB, $jsonSchema and text indexes aren't supported, and a transaction must stay inside one unsharded collection.
  • Both have a free tier, one per Azure subscription, and everything past it is billed. This course creates nothing on Azure.

You'll meet this one at a company that already runs on Microsoft's cloud, Azure. Someone asks, "Can our MongoDB app move to Azure without a rewrite?", or a job post lists "Cosmos DB" beside Node and MongoDB. This lesson tells you what you'd be moving to, what stays the same, and what to check first. It describes the services as Microsoft's documentation did when the lesson was written, and it creates nothing: no Azure account, nothing that costs money.

Two Azure services that speak MongoDB

The Maple Street Pet Adoption Center gets a grant that pays for Azure, and the board wants the pet API there too. Microsoft offers two services a MongoDB app can talk to:

  • Azure Cosmos DB for MongoDB is part of Azure Cosmos DB, Microsoft's NoSQL database, which also offers other APIs (ways in) for other kinds of code. You pay for its work in request units, below.
  • Azure DocumentDB (with MongoDB compatibility) was called vCore-based Azure Cosmos DB for MongoDB until it was renamed. You pay for its servers: vCores (virtual processors) and storage. It's built on DocumentDB, an open-source engine, and Microsoft says it supports MongoDB versions 4.0 through 8.0 and 99.03% of MongoDB's operators.

Here's the honest part both share: neither runs MongoDB's own server. Each one speaks MongoDB's wire protocol, the language a driver and the server use to talk, the way a phone can call any carrier's number. So the official drivers, Mongoose, mongosh and Compass connect to them as if they were MongoDB.

What changes for your code

Often, one line: the connection string. The pet API reads it from MONGODB_URI in .env, so for Cosmos DB for MongoDB it would hold the string the Azure portal shows on its Connection strings page, in this shape:

MONGODB_URI=mongodb://<account>:<password>@<account>.mongo.cosmos.azure.com:10255/?ssl=true

The account name is the user name, the port is 10255, and ssl=true is required, because Azure only accepts encrypted connections. Copy the whole string from the portal, which adds a few options of its own, and keep it out of Git, like any password.

"Often" isn't "always". Each service supports most of MongoDB, not all of it, so the move only counts as done when every query and test the app has runs against the new service.

What differs on Cosmos DB for MongoDB

Microsoft's feature list for server version 7.0 has these differences that matter for what this course built:

On your own MongoDB On Azure Cosmos DB for MongoDB
$jsonSchema validators Not supported
Text indexes and $text Not supported; Microsoft suggests $regex
A transaction across collections Only inside one unsharded collection, finished within 5 seconds
$lookup Supported, except the form with let and pipeline
Documents up to 16 MB 2 MB, unless the account turns on 16 MB support
As many requests as the server can handle A budget of request units per second, then error 16500

A request unit, or RU, is how Cosmos DB measures work: reading one 1 KB document by its id costs about 1 RU, and bigger documents and harder queries cost more. With provisioned throughput you choose a budget, such as 400 RU/s, and pay for it by the hour, used or not. In serverless mode you pay for the RUs your requests use. When requests need more than the budget, Cosmos DB refuses them with error code 16500, TooManyRequests, and your app has to retry (Cosmos DB can retry for you if server-side retry is turned on) or you raise the budget. A local MongoDB never says that.

What costs money, and the free options

Everything on Azure needs an Azure account, and anything beyond a free allowance goes on a bill. The free allowances, as Microsoft describes them:

  • Cosmos DB's free tier: the first 1000 RU/s and 25 GB of storage on one account per Azure subscription, for the life of the account. You opt in when you create the account, it isn't available in serverless mode, and use past those limits is billed.
  • DocumentDB's free tier: one cluster per subscription with 32 GB of storage, in a limited set of regions, with no backups, and paused after 60 days without use.

Choose either when the app already lives on Azure and the team wants one bill and one set of tools. For learning, your own MongoDB, or Atlas from Another Way: A Free Cluster on MongoDB Atlas, runs every query in this course exactly as written.

Check yourself

2 questions to try on the lesson page.

So what

"MongoDB-compatible" means your code connects without a rewrite, not that every feature is there. Change the connection string, then run every test before you trust the move.

Sources

Key terms

Related