Cosmos DB and Azure DocumentDB

An Azure Cosmos DB account is the top-level resource: it fixes the API (below), the Azure regions the data is replicated to, and the account-wide settings (consistency default, capacity mode, network rules) that every database underneath it inherits. Within an account:

Every item in a container carries a partition key — a property (or, since composite partition keys, several) whose value groups items into logical partitions. Cosmos DB transparently maps logical partitions onto physical partitions, splitting and rebalancing them automatically as data and throughput grow; an application never addresses a physical partition directly, but its choice of partition key entirely determines how RU throughput and storage get spread across them. The figure below shows the mapping and the pitfall that follows from it:

A well-chosen partition key (Bookshelf uses customerId for its orders container) has high cardinality and spreads both storage and request volume evenly. A hot partition results from a key with low cardinality or a skewed access pattern — a single logical partition value that draws disproportionate RU demand (a celebrity product SKU, a single large tenant in a multi-tenant container, a key derived from a coarse date bucket that every write of the day lands on) — because provisioned RU/s is split roughly evenly across physical partitions, not pooled across the container: a hot logical partition can throttle (HTTP 429, TooManyRequests) even while the container’s aggregate RU/s utilization looks low. az cosmosdb sql container throughput show (and the portal’s Insights → Throughput → Normalized RU Consumption by PartitionKeyRangeId view) surface this per-physical-partition skew; the fix is almost always changing the partition key (which requires recreating the container and migrating data, since the key is immutable), never simply raising throughput.

References: Partitioning and horizontal scaling in Azure Cosmos DB, Model and partition data in Azure Cosmos DB using a real-world example, Monitor normalized request unit (RU/s) consumption.

A request unit (RU) is Cosmos DB’s normalized cost currency for every database operation — a 1 KB point read costs roughly 1 RU; a point write, a few times that (indexing every property adds further RU); a cross-partition query with no useful index can cost well over 100 RU. The figure above also breaks down approximate RU cost by operation type. Throughput is purchased in one of three modes, chosen per database (shared) or per container (dedicated):

Cosmos DB lets an account pick a default point on a well-defined consistency spectrum, trading read latency and availability against how strictly reads observe writes — and any individual request can override the account default to a weaker level (never a stronger one) at request time:

Strong and Bounded Staleness read from a quorum of replicas, which is why they carry roughly double the RU cost per read compared to Session, Consistent Prefix, and Eventual (which read a single replica). The account default is set at creation (--default-consistency-level above) and can be changed later, but changing it does not retroactively affect data already replicated under the previous setting’s guarantees.

References: Consistency levels in Azure Cosmos DB, Consistency, availability, and performance tradeoffs, Manage consistency in Azure Cosmos DB.

A Cosmos DB account can replicate to any number of Azure regions, added or removed without downtime; each region holds a full copy of every partition. By default one region is designated the write region (single-write, multi-read) and the rest serve reads only, with automatic failover promoting a new write region by configured priority if the current one becomes unavailable; alternatively, an account can enable multi-region writes (sometimes still called multi-master), letting every region accept writes and relying on last-writer-wins (or a custom conflict resolution policy/stored procedure) to reconcile concurrent writes to the same item across regions. Multi-region writes trades that added complexity for the lowest possible write latency in every region and continuous write availability during a regional outage, and is incompatible with the Strong consistency level.

Two backup modes exist, chosen at account creation and not changeable to the other mode afterward without migrating: periodic backup (a full backup taken on an interval, restorable only by opening a support request) and continuous backup, which streams changes continuously and allows a self-service restore to any point in time within a 7-, 30-, or 35-day retention window (tier-dependent) into a new account — restoring in place is not supported, since a restore always creates a separate target account. A restored account does not carry over data-plane RBAC role assignments (Data-plane RBAC and disabling key-based auth); those must be re-applied to the restored account after the restore completes. Continuous backup also requires a single write region, which is why the examples below use a separate docdb-bookshelf-backup account rather than the multi-region-write docdb-bookshelf account above.

Cosmos DB separates management-plane access (Azure RBAC roles like Contributor, controlling the account resource itself) from data-plane access (reading/writing items), the latter authorized through Cosmos DB’s own built-in role definitions (Cosmos DB Built-in Data Reader, Cosmos DB Built-in Data Contributor) assigned with az cosmosdb sql role assignment create — distinct from, and not implied by, an Azure RBAC role on the account. As with Blob Storage’s Shared Key model (see Identity and Access for the general Entra ID pattern this mirrors), Cosmos DB also supports legacy primary/secondary account keys that bypass data-plane RBAC entirely. Setting the account’s disableLocalAuth property to true rejects every key-authenticated data-plane request, which forces every client onto Entra ID authentication via DefaultAzureCredential. (The separate --disable-key-based-metadata-write-access flag only stops account keys from creating or changing databases and containers; it does not stop keys from reading or writing data.)

The Azure Cosmos DB Linux-based emulator runs as a Docker container (mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator) on Linux, macOS, or Windows, exposing the NoSQL API locally with no Azure subscription or network access required — the successor to the older Windows-only emulator, which remains available but is no longer the recommended starting point. It supports a useful but incomplete subset of server behavior (in particular, global distribution and multi-region behavior cannot be exercised locally), so it is best treated as a fast inner-dev-loop and integration-test target, not a substitute for testing against a real account before a release.

References: Linux-based emulator for Azure Cosmos DB, Use the Azure Cosmos DB emulator for local development and testing.

In November 2025, Microsoft renamed "Azure Cosmos DB for MongoDB (vCore)" to Azure DocumentDB — a first-party rebrand of the same dedicated-cluster, MongoDB-wire-protocol-compatible product, not a retirement or a different service. The name reuses "Azure DocumentDB", which from 2014 to 2017 was Microsoft’s name for the service that became Azure Cosmos DB; neither should be confused with Amazon DocumentDB (AWS’s MongoDB-compatible service). The open-source documentdb project is the engine today’s Azure DocumentDB is built on. Azure DocumentDB is priced and operated like a managed MongoDB cluster (vCore-based compute and storage sized per node, much closer to how MongoDB Atlas or a self-run mongod replica set is priced) rather than Cosmos DB’s RU model covered above; the RU-priced Cosmos DB MongoDB API remains a separate, still-supported product for workloads already built against it, and Microsoft’s own migration tooling (below) exists specifically because the two are not the same underlying engine.

Bookshelf’s orders service is modeled on this page using the NoSQL API’s docdb-bookshelf account for the canonical example, with the DocumentDB CLI walkthrough above showing the alternative MongoDB-compatible path under the same resource name for a team that would rather keep the driver/tooling MongoDB-native.

References: Choosing between Azure Cosmos DB, Azure DocumentDB, and MongoDB Atlas, MongoDB’s own comparison of MongoDB, Azure DocumentDB, and Cosmos DB, MongoDB Atlas on Azure Marketplace.

Cosmos DB’s RU-based pricing (provisioned/autoscale/serverless, plus storage and networking) is published at the Cosmos DB pricing page; DocumentDB’s vCore-based pricing (per shard-node tier, storage, and backup) is published separately at the Azure DocumentDB pricing page — the two are not on a shared price list, matching their different billing models above. The most consequential recent change is the November 2025 rename covered in Azure DocumentDB: any documentation, blog post, or third-party tooling still referring to "Cosmos DB for MongoDB (vCore)" is describing today’s Azure DocumentDB under its former name, not a separate or deprecated product. Treat any specific rate or free-tier term stated on this page as indicative, not contractual, and re-check both pricing pages plus the Azure DocumentDB release notes before committing to a sizing decision.

Application-level MongoDB concepts — documents and BSON, the aggregation pipeline, indexes, sharding, replication, drivers — apply equally whether the backing service is Atlas, self-hosted MongoDB, or Azure DocumentDB’s MongoDB-compatible cluster; they are covered in depth on the MongoDB reference rather than repeated here. This page’s Cosmos DB NoSQL sections above cover Cosmos-specific concepts (partitioning, RUs, consistency levels) that have no MongoDB equivalent.

This removes every Cosmos DB account and DocumentDB cluster created in $RG on this page, including docdb-bookshelf and any restored/backup accounts. A locked continuous-backup retention setting does not block this account-level deletion the way a locked immutability policy blocks a Blob Storage container delete.