Cosmos DB API for MongoDB - Azure Glossary

Understand the concept

In plain English

Cosmos DB API for MongoDB lets applications that already use MongoDB-style documents connect to Azure Cosmos DB with familiar drivers and tools. Developers can keep a document model, collections, and many MongoDB coding patterns while Azure provides managed database operations, scaling, regions, monitoring, and backup. It is useful for migrations, modernization, and new document workloads that prefer MongoDB compatibility. The key lesson is that compatibility does not remove the need to design partitioning, throughput, indexing, security, and service limits for Cosmos DB specifically.

Why it matters

Cosmos DB API for MongoDB matters because document applications often need a cloud-managed path without rewriting every repository, driver call, or data model. It can shorten migration timelines and give teams Azure-native monitoring, global distribution, backup, and security controls. The practical risk is assuming the service is identical to every MongoDB deployment. Query plans, aggregation support, index behavior, partitioning, transactions, and cost can differ enough to affect production. Good teams test critical workloads, not just connection success. This term helps readers understand that the API is both a compatibility layer and an Azure Cosmos DB design decision. This prevents teams from turning a platform option into an undocumented production assumption.

Official wording and source

Azure Cosmos DB for MongoDB is a fully managed Cosmos DB API that supports MongoDB workloads through MongoDB-compatible drivers, tools, and connection strings.

Open Microsoft Learn

Technical context

Technically, Cosmos DB API for MongoDB is created as a MongoDB-capable Cosmos DB account with databases and collections exposed through MongoDB-compatible connection strings. Applications use MongoDB drivers, but requests are served by Cosmos DB infrastructure with request units, regional replication, consistency, backup, and network controls. Architects should verify supported server features, index behavior, partition key strategy, transaction expectations, aggregation patterns, and driver versions. Operational work includes private networking, key rotation, diagnostics, throughput scaling, restore planning, and testing how production queries consume RU under realistic document sizes.

Exam context

Compare with

Azure Cosmos DB Database

Where it is used

Where you see it

In the Azure portal, it appears on Cosmos DB accounts, MongoDB databases, collections, connection strings, index settings, throughput screens, and networking configuration during production reviews and runbooks.
In application repositories, it appears as MongoDB driver usage, collection names, connection-string settings, aggregation pipelines, index definitions, retry policies, and migration adapters in release reviews and support tickets.
In operations data, it appears beside RU consumption, 429 throttling, collection storage growth, slow aggregations, driver exceptions, key rotation events, and restore testing records during incident triage and architecture reviews.

Common situations

Modernize MongoDB-style document applications on managed Azure infrastructure.
Migrate document databases while keeping familiar drivers and tools.
Scale globally distributed document workloads with Cosmos DB monitoring and backup.
Build new document apps that require MongoDB-compatible access patterns.

Illustrative Azure scenarios

These examples show how the concept can affect design and operations. They are illustrative scenarios, not customer claims.

Scenario 01 Subscription platform migration Scenario, objectives, solution, measured impact, and takeaway.

Scenario

BluePeak Media ran subscriber profiles on self-managed MongoDB and needed global availability for a streaming expansion.

Goals

Move 35 million profile documents with minimal code change
Keep profile reads below 50 milliseconds in launch regions
Reduce database patching and failover administration
Protect subscription and viewing-preference data

Approach using Cosmos DB API for MongoDB

The engineering team created Cosmos DB API for MongoDB accounts in two regions and migrated profile collections in phased batches. Existing Node.js services kept MongoDB drivers but moved connection strings to Key Vault and private endpoints. Architects reviewed partition keys, indexes, document size, and aggregation pipelines before each service cutover. Autoscale throughput was load tested using real viewing-event patterns, while Azure Monitor tracked RU, 429 responses, latency, and driver errors. A rollback plan kept the old cluster read-only until validation confirmed profile counts and critical queries. The final review documented service owners, rollback triggers, monitoring thresholds, and escalation contacts so production support could act without guessing.

Potential outcomes

Profile reads averaged 37 milliseconds in the first two launch regions
Code changes were limited to configuration and two query adjustments
Monthly database maintenance hours dropped 54 percent
Security review confirmed private endpoint use and rotated legacy secrets

What to learn

Cosmos DB API for MongoDB is useful when MongoDB-style applications need managed Azure operations, but query and partition validation still decide success.

Scenario 02 Government forms modernization Scenario, objectives, solution, measured impact, and takeaway.

Scenario

CityLink Services stored permit applications as MongoDB documents and needed resilient online filing during seasonal surges.

Goals

Support 12,000 permit submissions per hour
Preserve flexible document fields for different permit types
Improve backup and restore confidence for public records
Give auditors clear access and change evidence

Approach using Cosmos DB API for MongoDB

Architects deployed Cosmos DB API for MongoDB with collections for permit applications, applicant profiles, payment status, and workflow events. Partition keys were selected from filing region and permit identifiers after testing expected surge patterns. The migration team rebuilt indexes for the most common status and date queries, then measured RU charge before launch. Private networking, diagnostic logs, backup-policy review, and RBAC-separated operations were added to the runbook. Auditors received evidence from Azure Monitor logs and restore drills rather than informal export spreadsheets. A follow-up runbook captured validation queries, owner approvals, cost guardrails, and support handoff steps for the next release. Operations also added a quarterly review to confirm metrics, access, backup assumptions, and application behavior still matched the original design.

Potential outcomes

Submission capacity exceeded 13,500 per hour in load testing
Permit status queries stayed below 45 milliseconds P95
Restore rehearsal met the two-hour public-records recovery target
Audit evidence preparation time fell from three days to one day

What to learn

The MongoDB API can modernize flexible public-sector document data when governance, restore, and query-cost evidence are built into the design.

Scenario 03 SaaS tenant catalog cleanup Scenario, objectives, solution, measured impact, and takeaway.

Scenario

NimbusWorks Software used multiple MongoDB clusters for tenant configuration and wanted one managed platform with clearer cost ownership.

Goals

Consolidate tenant catalog data into managed Azure accounts
Keep tenant lookup latency below 35 milliseconds
Tag cost by product line and environment
Eliminate unmanaged administrator credentials

Approach using Cosmos DB API for MongoDB

The SaaS platform team moved tenant, feature-flag, billing-plan, and integration collections into Cosmos DB API for MongoDB. Collections were grouped by environment, and tags aligned spend with product teams. Driver configuration was standardized across microservices, while secrets moved from environment files into Key Vault references. Indexes were reviewed for tenant lookup and feature evaluation paths, and autoscale limits were set from production traffic replay. Operations dashboards separated RU, storage, and throttling by account, making noisy services visible without giving every team administrative access. Operations also added a quarterly review to confirm metrics, access, backup assumptions, and application behavior still matched the original design. The final review documented service owners, rollback triggers, monitoring thresholds, and escalation contacts so production support could act without guessing.

Potential outcomes

Tenant lookup P95 latency improved from 49 to 28 milliseconds
Unmanaged database administrator credentials were removed from 18 services
Product-line cost allocation reached 96 percent coverage
Cluster consolidation reduced database operations incidents by 41 percent

What to learn

Compatibility with MongoDB tooling can simplify SaaS modernization, but standardized operations and cost tagging make the platform sustainable.

Azure CLI

Use CLI to verify the MongoDB API account, list databases and collections, review throughput, and gather evidence before migration or production tuning.

Useful for

Confirm an account is configured for MongoDB-compatible workloads.
List MongoDB databases and collections during migration assessment.
Check collection throughput before investigating throttling or slow queries.

Before you run a command

Confirm the subscription, resource group, account, database, and collection names.
Run read-only commands before modifying throughput or collection settings.
Coordinate with application owners before rotating keys or changing network access.

What the output tells you

Account output confirms regions, backup mode, network posture, and API kind.
Database and collection output identifies the resources application code depends on.
Throughput output helps correlate cost, throttling, and performance symptoms.

Mapped commands

Cosmos DB API for MongoDB commands

direct

az cosmosdb show --name <account> --resource-group <resource-group>

az cosmosdbdiscoverDatabases

az cosmosdb mongodb database list --account-name <account> --resource-group <resource-group>

az cosmosdb mongodb databasediscoverDatabases

az cosmosdb mongodb collection list --account-name <account> --resource-group <resource-group> --database-name <database>

az cosmosdb mongodb collectiondiscoverDatabases

az cosmosdb mongodb collection throughput show --account-name <account> --resource-group <resource-group> --database-name <database> --name <collection>

az cosmosdb mongodb collection throughputdiscoverDatabases

Architecture context

Cosmos DB API for MongoDB is an application compatibility choice that still requires Cosmos DB architecture discipline. I use it when teams want MongoDB-style drivers and document access but need managed distribution, Azure networking, and account-level governance. During design, I focus on version compatibility, partition strategy, indexing, request-unit behavior, connection settings, backup mode, and regional latency. Migration plans should test real queries and aggregation patterns, not just successful connection strings. Operators should inspect collections, throughput, index definitions, throttling, slow queries, and driver errors before declaring parity with an existing MongoDB estate. The API can reduce operational burden, but teams must understand where Cosmos DB semantics, RU costs, and supported features differ from their source environment.

Security: Security for Cosmos DB API for MongoDB should cover account keys, connection strings, firewall rules, private endpoints, approved client networks, diagnostic logs, and administrator roles. MongoDB applications often carry secrets in configuration files, containers, or CI variables, so migration must include secret cleanup and rotation. Data classification matters because document collections may contain nested personal or financial fields that are easy to expose through broad queries. Review whether support tools, BI exports, or migration utilities have excessive access. Security checks should prove that public network access is controlled, credentials are rotated, least-privilege operations are documented, and failed connection attempts are visible.
Cost: Cost for Cosmos DB API for MongoDB is influenced by request units, storage, regions, backups, monitoring, and query efficiency. Existing MongoDB teams may think in clusters or server tiers, but Cosmos DB cost is tied closely to throughput and data volume. Large documents, unselective queries, missing or mismatched indexes, high autoscale ceilings, and replicated regions can raise spend quickly. Cost reviews should examine RU per operation, collection growth, peak traffic, analytical exports, and migration validation environments. Budget owners need alerts that connect spend to applications, not just account names, so teams can tune queries before cost becomes an incident. Tie every cost decision to measured workload behavior and named budget ownership.
Reliability: Reliability for Cosmos DB API for MongoDB depends on account regions, consistency settings, backup policy, partitioning, throughput headroom, index design, and driver retry behavior. A migration that passes small tests can still fail when production traffic creates hot partitions, expensive aggregations, or retry storms after throttling. Teams should define recovery objectives, restore steps, failover expectations, and acceptable error handling for application services. Monitor 429 responses, request charge, latency percentiles, normalized RU, storage growth, and regional health. Reliability drills should include bad data writes, accidental collection deletion, driver version changes, and regional outage scenarios. Include realistic failure drills, owner escalation, and recovery evidence in the runbook.
Performance: Performance for Cosmos DB API for MongoDB is shaped by partition keys, index definitions, document size, aggregation patterns, throughput, consistency, region distance, and driver configuration. Applications should prefer targeted reads and writes that align with partitioning rather than broad cross-partition queries. Test the exact MongoDB driver version, indexes, and aggregation pipelines used in production because compatibility does not guarantee identical performance. Monitor latency percentiles, request charge, throttling, and query diagnostics during load tests. Performance work often means changing indexes, query filters, document shape, or autoscale settings before adding more throughput. Validate tuning with representative traffic, documented baselines, and user-facing service targets.
Operations: Operationally, Cosmos DB API for MongoDB needs a clear map of accounts, databases, collections, partition keys, indexes, applications, drivers, and owners. Support teams should know which collections are business critical, which queries are approved, and which migrations or analytics jobs can be paused when RU pressure appears. Runbooks should include CLI discovery, connection string rotation, throughput updates, backup verification, index review, and troubleshooting for driver errors. Migration projects should retain compatibility test results and known limitations. Good operations prevent a familiar MongoDB interface from hiding Azure-specific responsibilities around scaling, monitoring, cost, and recovery. Keep ownership, dashboard links, deployment history, and support escalation steps current.

Common mistakes

Treating connection success as complete MongoDB compatibility validation.
Ignoring partition key and RU behavior during migration planning.
Leaving old MongoDB connection strings or secrets in deployment pipelines.