Get answers to frequently asked questions about Azure DocumentDB (with MongoDB compatibility): what it is, how compatible it is with MongoDB, the TCO savings achievable, and how to migrate.
General
What is Azure DocumentDB?
Azure DocumentDB (with MongoDB compatibility) is a fully managed, MongoDB-compatible document database on Azure. Existing MongoDB drivers, tools, and application code connect without changes, and Azure DocumentDB supports 99.03% of MongoDB operators. Azure DocumentDB is built on DocumentDB, an open-source document database governed by the Linux Foundation, released under the MIT license, and built on PostgreSQL. For an introduction, see What is Azure DocumentDB?.
Is Azure DocumentDB a drop-in replacement for MongoDB?
Yes, for most applications. Azure DocumentDB implements the MongoDB wire protocol, so MongoDB drivers, MongoDB Compass, the MongoDB shell (mongosh), and frameworks such as Mongoose and Spring Data connect without code changes. Azure DocumentDB supports 99.03% of MongoDB query, projection, update, and aggregation operators. To check your own workload, run the free compatibility assessment in the Azure DocumentDB migration extension for Visual Studio Code. See MongoDB compatibility.
What workloads is Azure DocumentDB best suited for?
Azure DocumentDB suits any workload that runs on MongoDB today: operational and transactional applications, web and mobile back ends, content and catalog management, real-time analytics with aggregation pipelines, and AI applications that use vector search. Azure DocumentDB is the recommended managed option for teams moving MongoDB from Azure virtual machines, MongoDB Atlas, Amazon DocumentDB, or on-premises servers.
Are there workload categories beyond MongoDB for which Azure DocumentDB is suited?
Azure DocumentDB is suitable for new applications and agent driven workloads that need to get started quickly, iterate rapidly, and scale efficiently. It provides an integrated document data store, vector database (with DiskANN) and search capabilities, all managed and contained within the same deployment. This makes building new apps, and agent driven frameworks very efficient.
How does Azure DocumentDB relate to Azure Cosmos DB?
Azure DocumentDB was previously named vCore-based Azure Cosmos DB for MongoDB. It became its own distinct offering to align with the open-source DocumentDB project that powers it. The rename didn't change existing clusters, connection strings, or APIs. Azure DocumentDB and Azure Cosmos DB for MongoDB (RU) are separate services: Azure DocumentDB uses dedicated vCore-based clusters, and Azure Cosmos DB for MongoDB (RU) uses request-unit-based throughput.
Is Azure DocumentDB the same as Amazon DocumentDB?
No. Azure DocumentDB and Amazon DocumentDB are unrelated services from different companies. Azure DocumentDB is a Microsoft Azure service built on the open-source DocumentDB engine, and supports 99.03% of MongoDB operators. Azure DocumentDB is also unrelated to the original Azure DocumentDB service from 2014 to 2017, which became Azure Cosmos DB. You can migrate from Amazon DocumentDB to Azure DocumentDB. See Migration options.
Does MongoDB's SSPL license apply to Azure DocumentDB?
No. Azure DocumentDB doesn't run the MongoDB database server or its codebase, so MongoDB's Server Side Public License (SSPL) doesn't apply. Azure DocumentDB is built on the open-source DocumentDB engine, which is released under the permissive MIT license.
Can I run the same database on-premises or on other clouds?
Yes. The open-source DocumentDB engine that powers Azure DocumentDB runs on-premises and on any cloud through the DocumentDB Kubernetes operator. Applications use the same MongoDB-compatible drivers and interface everywhere, and Azure DocumentDB supports cross-cloud replication and failover with self-hosted DocumentDB.
How do I get started with Azure DocumentDB?
Start with the free tier, which gives you a dedicated cluster with 32 GB of storage at no cost. You can create a cluster from the Azure portal, the Azure CLI, Bicep, or Terraform. See Azure DocumentDB free tier, Quickstart: Azure portal, and Quickstart: Bicep.
Does Azure DocumentDB offer a service level agreement (SLA)?
Yes. Azure DocumentDB offers a 99.995% availability SLA for highly available configurations. The SLA covers the full stack: the database, compute, storage, and networking. Free tier clusters and clusters without high availability have different terms. For details, see the SLA for online services.
Cost and pricing
How does pricing work for Azure DocumentDB?
Azure DocumentDB pricing is based on two things: compute (the cluster tier, in vCores and memory) and storage. You scale compute and storage independently. There are no request units, no per-operation I/O charges, and no separate charges for backups or high-performance storage. Reserved capacity saves up to 40% with a one-year commitment and up to 60% with three years, and Azure DocumentDB is eligible for the savings plan for databases. See Azure DocumentDB pricing.
How much cheaper is Azure DocumentDB than MongoDB Atlas?
Azure DocumentDB costs at least 40% less than MongoDB Atlas for equivalent compute. Most customers save more than 50% in total, because Azure DocumentDB doesn't charge separately for backups or networking. For a feature-by-feature comparison, see Compare Azure DocumentDB with MongoDB Atlas.
What's included in the price at no extra cost?
Azure DocumentDB includes these at no extra cost:
- Backups, with point-in-time restore for up to 35 days for Production tiers (M30 and larger SKUs).
- Premium SSD v2 high-performance storage.
- Integrated text search and vector search, with no separate search tier.
- Support through your existing Azure support plan.
- The Azure DocumentDB migration extension and compatibility assessment.
Can I lower costs for development and test environments?
Yes. Azure DocumentDB lets you run clusters without high availability for development and test, which costs less than a highly available production cluster. You can also use the free tier for development, testing, and small workloads.
Does Azure DocumentDB count toward my Azure commitment?
Azure DocumentDB is a first-party Azure service, so usage appears on your Azure invoice and is covered by your Azure support plan.
Free tier
Does Azure DocumentDB have a free tier?
Yes. The Azure DocumentDB free tier gives you a dedicated cluster with 32 GB of storage, free for the lifetime of your Azure account. That's 64 times the storage of the MongoDB Atlas free tier, which offers 512 MB. Free tier clusters provision in seconds. Each Azure subscription can have one free tier cluster. See Azure DocumentDB free tier.
What are the limits of the free tier?
The Azure DocumentDB free tier doesn't include high availability, Microsoft Entra ID authentication, backup and restore, DiskANN or HNSW vector indexes, or diagnostic logging. Azure DocumentDB pauses free tier clusters after 60 days of inactivity. The free tier is available in a subset of Azure regions. See Azure DocumentDB free tier for the current list. The free tier is meant to be used for early day prorotyping and functional validation. For anything larger, a scale up to a paid tier is recommended.
Can I upgrade a free tier cluster to a paid tier?
Yes. You can upgrade an Azure DocumentDB free tier cluster to any paid tier in place. Your data, connection string, and network rules stay the same. You can't move a paid cluster back to the free tier.
MongoDB compatibility
Which MongoDB versions and features does Azure DocumentDB support?
Azure DocumentDB supports MongoDB wire protocol versions 5.0, 6.0, 7.0, and 8.0, and 99.03% of MongoDB query, projection, update, and aggregation operators. The percentage counts are based on the supported user facing MongoDB operators. It excludes administrative commands, which Azure DocumentDB manages as a platform service. For details, see MongoDB Query Language (MQL) compatibility and MongoDB feature compatibility.
Are MongoDB drivers and tools compatible with Azure DocumentDB?
Yes. Any driver that supports the MongoDB wire protocol connects to Azure DocumentDB, including the official MongoDB drivers for Node.js, Python, Java, .NET, Go, and other languages. Tools such as MongoDB Compass and the MongoDB shell (mongosh) also work. MongoDB-specific storage engines and server-side extensions aren't supported, because Azure DocumentDB doesn't run the MongoDB server.
Are there any differences in behavior I should expect after migration?
Most applications behave the same. Differences can appear in some administrative commands, which Azure DocumentDB manages for you, and in the small set of operators that aren't supported. Run the compatibility assessment before you migrate, and test your workload on a staging cluster. See MongoDB compatibility for the list of unsupported operators.
How do I verify that my application is compatible before migrating?
Run the free compatibility assessment in the Azure DocumentDB migration extension for Visual Studio Code. It scans your source MongoDB deployment and reports unsupported features, commands, query syntax, and index types. Then run your integration tests against a test cluster, which can be a free tier cluster. See Assess and plan migration readiness.
Migration
Can I migrate my existing MongoDB database to Azure DocumentDB?
Yes. Azure DocumentDB supports migrations from MongoDB Atlas on any cloud, Amazon DocumentDB, self-hosted MongoDB on virtual machines, and self-hosted MongoDB on-premises. The migration tools are free to use. See Migration options.
Which tools can I use to migrate to Azure DocumentDB?
You can use any of these tools:
- Azure DocumentDB migration extension for Visual Studio Code: assess compatibility, then run online or offline migrations by database or collection. See Migrate using the migration extension.
- Azure Database Migration Service: run migration jobs from the Azure portal that keep running after you close the browser. See Migrate using Azure Database Migration Service.
- Native MongoDB tools: use mongodump and mongorestore, or mongoexport and mongoimport, for offline migrations. See Migrate using native MongoDB tools.
Can I migrate without downtime?
Yes, with minimal downtime. An online migration copies your data, then keeps the target in sync with your source through change streams while your application keeps running. You switch your application to Azure DocumentDB at cutover. Online migration requires change streams to be enabled on the source and an oplog large enough to cover the migration window.
How do I migrate from MongoDB Atlas to Azure DocumentDB?
Run the compatibility assessment, create an Azure DocumentDB cluster sized to your workload, and then run an online migration with the migration extension or Azure Database Migration Service. Atlas clusters on Azure, AWS, and Google Cloud are all supported sources. See Migration options.
How do I migrate from Amazon DocumentDB to Azure DocumentDB?
Enable change streams on your Amazon DocumentDB cluster, run the compatibility assessment, and then run an online migration with the migration extension or Azure Database Migration Service. See Migration options.
Security
How is data protected at rest in Azure DocumentDB?
Azure DocumentDB encrypts all data at rest by default. You can use service-managed keys (SMK) or customer-managed keys (CMK) for an additional layer of encryption. See Encryption at rest.
What transport-level encryption does Azure DocumentDB use?
Azure DocumentDB enforces Transport Layer Security (TLS) for all client and service connections. Make sure your clients use current TLS versions and trusted root certificates.
How do I manage authentication and access control?
Azure DocumentDB supports native (built-in) authentication and Microsoft Entra ID for centralized identity and access management. You can create granular users and roles at the database and collection level, and use managed identities for service-to-service authentication. See Microsoft Entra ID authentication and Security best practices.
Can I run Azure DocumentDB behind a firewall and Private Link?
Yes. Firewall rules restrict public access, and Azure Private Link exposes your Azure DocumentDB cluster through private endpoints in your virtual network. Private endpoints are reachable from virtual network resources and from on-premises networks connected to that virtual network. See Use Azure Private Link and Manage public access.
How should I manage encryption keys when using CMK?
When you use customer-managed keys with Azure DocumentDB, you manage the key lifecycle in Azure Key Vault. Follow these practices:
- Enable logging and alerts on the key vault.
- Lock the key vault resource.
- Plan key rotation.
- Make sure Azure DocumentDB has network access to the key vault to retrieve the key.
For more information, see Configure CMK.
What are recommended security monitoring and logging practices?
Monitor and alert on free Azure DocumentDB metrics through Azure Monitor or detailed request level monitoring in Log Analytics, which incurs a cost on the Log Analytics workspace. Audit administrative actions and configure alerts for suspicious activity. Diagnostic logging isn't available on the free tier.
Connectivity
How do clients connect to an Azure DocumentDB cluster?
Clients connect with standard MongoDB drivers, using the cluster's connection string. You can connect over the public endpoint, protected by firewall rules, or privately through Private Link. See the language quickstarts for examples, such as Quickstart: Node.js.
What options exist for restricting network access?
Use cluster firewall rules to restrict source IP addresses, Private Link to create private endpoints in your virtual networks, and network security groups and virtual network peering for finer control. See Manage public access and Use Azure Private Link.
Can I connect from on-premises networks?
Yes. On-premises resources connected through VPN or Azure ExpressRoute to a peered virtual network can reach Azure DocumentDB Private Link endpoints. You can also use the public endpoint with firewall rules, but private connectivity is recommended for production workloads.
How do I configure connection strings and driver settings?
Use the standard MongoDB connection string format with your driver. Include options for TLS and your authentication mechanism (username and password, or Microsoft Entra ID). See the language-specific quickstarts for examples.
How do I reduce latency for users in multiple regions?
Network distance between your application and the cluster affects latency. Deploy your Azure DocumentDB cluster in the same region as your application, and add read replicas either locally or in other regions for users elsewhere. See High availability and replication best practices.
Performance and scaling
How do I scale performance in Azure DocumentDB?
Scale an Azure DocumentDB cluster up by choosing a larger cluster tier with more vCores and memory, and scale storage separately as your data grows. Scale out by adding shards. Because compute and storage scale independently, you don't need to buy more compute just to get more storage. See Scale or configure a cluster.
Can I decrease the storage size of my cluster?
No. Storage size can only be increased, not decreased.
When should I shard my data?
Most workloads don't need sharding until a database reaches multiple terabytes, because a single Azure DocumentDB node supports up to 32 TB of storage. When you do shard, choose a shard key with high cardinality and even distribution. You can shard existing collections online, with no downtime. See Sharding and Indexing.
Can the same Azure DocumentDB cluster support both sharded and un-sharded collections?
Yes, and this is a common pattern. Multi-shard Azure DocumentDB clusters can support un-sharded collections where collections are not distributed across shards and reside entirely on a single node. In this configuration, multiple large collections can be separated across different nodes, allowing for better resource utilization and management. In addition, larger collections can be sharded, while smaller collections remain un-sharded. Lastly, all collections can be sharded and distrbuted across the physical shards in the Azure DocumentDB cluster.
What are best practices for indexing and query performance?
Create indexes that match your query patterns, avoid unbounded scans, and review query plans with explain() to find bottlenecks. Use Index Advisor for recommendations on common queries. See How to read explain out.
How do I monitor and troubleshoot performance issues?
Use Azure Monitor metrics for CPU, memory, storage, and IOPS, and diagnostic logs to capture slow queries. See Monitor metrics and Troubleshoot common issues.
Can Azure DocumentDB handle high read and write throughput?
Yes. Azure DocumentDB handles high-throughput workloads when the cluster tier, storage, and shard layout match the workload. Scale compute for more throughput, add shards to spread writes, and add read replicas to spread reads.