Cosmos DB API for NoSQL is the native document API most people mean when they talk about Azure Cosmos DB containers, items, SQL-style queries, partition keys, and request units. Applications store JSON items in containers and use SDKs or REST calls to read, write, query, and process changes. It is a strong fit for cloud-native apps that need low-latency document access and global distribution. The API is powerful, but success depends on partition design, query shape, consistency, indexing, throughput, and operational ownership.
Azure Cosmos DB for NoSQL, API for NoSQL, Core SQL API, SQL API
Difficulty
intermediate
CLI mappings
4
Last verified
Microsoft Learn
Azure Cosmos DB for NoSQL is the native Cosmos DB API for JSON document data, SQL-style queries, SDK operations, and globally distributed NoSQL applications.
Technically, Cosmos DB API for NoSQL organizes data into accounts, databases, containers, and JSON items. Containers define partition keys, indexing policy, throughput, time to live, unique keys, conflict policy, and optional analytical settings. Applications use SDKs, SQL-style queries, point reads, transactional batch within a logical partition, and the change feed. Architects must design for request units, logical partition size, consistency level, regional replication, backup mode, private networking, diagnostics, and SDK retry behavior. Most production outcomes trace back to container and partition decisions made early.
Why it matters
Cosmos DB API for NoSQL matters because it gives application teams a managed, globally distributed document database without forcing every workload into relational tables. It supports fast point reads, flexible JSON documents, change-driven processing, and elastic throughput. That flexibility can also hide expensive mistakes. A poor partition key, broad query, missing index decision, or mismatched consistency level can create cost, latency, or reliability problems. The term helps readers understand the core Cosmos DB operating model: account settings provide the platform boundary, containers define data behavior, and application code must align with partitioning and request-unit economics. This prevents teams from turning a platform option into an undocumented production assumption.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
In the Azure portal, it appears on Cosmos DB accounts, NoSQL databases, containers, items, partition-key settings, throughput screens, indexing policies, and change feed integrations during production reviews and runbooks.
Signal 02
In code, it appears as Cosmos SDK clients, SQL-style queries, point reads, transactional batches, partition-key values, continuation tokens, and change feed processors in release reviews and support tickets.
Signal 03
In monitoring, it appears beside request units, normalized RU, 429 throttling, query diagnostics, logical partition storage, latency percentiles, failover events, and backup status during incident triage and architecture reviews.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Build low-latency JSON document applications with global distribution.
Process operational changes through change feed consumers.
Store user profiles, carts, events, catalog data, and application state.
Scale cloud-native workloads with request-unit based capacity controls.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Checkout cart platform
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
Alpine Outfitters needed a globally available shopping-cart store before expanding same-day delivery into new regions.
🎯Business/Technical Objectives
Keep cart reads and writes under 25 milliseconds P95
Handle seasonal traffic spikes without manual server operations
Recover from accidental cart update bugs within one hour
Separate checkout access from analytics and support tooling
✅Solution Using Cosmos DB API for NoSQL
Architects built the cart service on Cosmos DB API for NoSQL with containers for carts, reservations, and checkout events. The cart container used customer id as the partition key after traffic analysis showed balanced distribution. SDK calls used point reads and transactional batch within a customer partition, while change feed processors updated downstream reservation services. Autoscale throughput covered seasonal peaks, private endpoints restricted network access, and continuous backup supported recovery drills. Azure Monitor tracked RU, latency, 429 responses, and change feed lag. The final review documented service owners, rollback triggers, monitoring thresholds, and escalation contacts so production support could act without guessing.
📈Results & Business Impact
Cart P95 operations stayed below 21 milliseconds during peak sale windows
Autoscale absorbed a 4.5x traffic spike without server provisioning
A test bad-write recovery completed in 37 minutes
Analytics identities were removed from direct cart write access
💡Key Takeaway for Glossary Readers
Cosmos DB API for NoSQL works well for cloud-native application state when partitioning, point reads, and recovery planning are engineered together.
Case study 02
Smart meter event store
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
GridNorth Energy collected meter events from millions of devices and needed faster regional reads for outage analysis.
🎯Business/Technical Objectives
Ingest 150,000 events per minute
Keep outage lookup latency below 75 milliseconds
Process event changes into alert workflows automatically
Track RU cost by region and device program
✅Solution Using Cosmos DB API for NoSQL
The data platform team used Cosmos DB API for NoSQL containers for meter events, device state, and outage summaries. Partition keys combined service territory and device identifiers to reduce hot partitions while supporting regional queries. Change feed processors pushed critical events into Azure Functions for alert enrichment, and lower-priority analytics exports were scheduled outside peak periods. Throughput, storage, and monitoring were tagged by program. Operators used CLI and dashboards to review container settings, normalized RU, and throttling before changing autoscale limits. 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.
📈Results & Business Impact
Event ingestion sustained 168,000 events per minute in production testing
Alert enrichment time dropped from 12 minutes to under two minutes
Regional cost attribution improved to 94 percent of monthly spend
💡Key Takeaway for Glossary Readers
The NoSQL API can support high-volume operational events when ingestion, change processing, and cost ownership are designed at the container level.
Case study 03
Patient portal records
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
MedicaWay Health wanted a responsive patient portal for preferences, visit summaries, and care-team messages across two regions.
🎯Business/Technical Objectives
Serve portal profile reads under 40 milliseconds
Protect patient data with private access and audited operations
Keep care-message processors from affecting login traffic
Validate backup and restore for portal-critical containers
✅Solution Using Cosmos DB API for NoSQL
Engineers used Cosmos DB API for NoSQL for portal profiles, preferences, visit summaries, and message metadata. The profile container used patient id for point reads, while message processors consumed change feed events with dedicated throughput controls. Private endpoints, Key Vault-backed configuration, diagnostic logs, and account-level access reviews were completed before release. Consistency and retry behavior were tested with the portal SDK, and operations runbooks documented how to pause noncritical processors if RU pressure affected patient login paths. Restore tests covered both deleted items and container-level recovery scenarios. Operations also added a quarterly review to confirm metrics, access, backup assumptions, and application behavior still matched the original design.
📈Results & Business Impact
Profile read P95 latency stayed at 29 milliseconds
No public network database access was allowed in production
Message processor throttling no longer affected login transactions
Restore testing met the 45-minute recovery objective
💡Key Takeaway for Glossary Readers
For regulated portals, Cosmos DB API for NoSQL is strongest when data access, change processors, and restore evidence are treated as one production design.
Why use Azure CLI for this?
Use CLI to inspect NoSQL databases, containers, throughput, and account settings before making design, support, or scaling decisions.
CLI use cases
List NoSQL databases and containers during application support.
Show container partition key, indexing, and throughput-related settings.
Capture account regions, backup mode, and consistency before architecture review.
Before you run CLI
Confirm the account, resource group, database, container, and environment.
Use read-only commands before changing throughput or indexing policies.
Coordinate changes with application teams and background processor owners.
What output tells you
Account output shows platform-level regions, consistency, networking, and backup context.
Container output shows partition key and policies that shape workload behavior.
Throughput output connects cost and throttling symptoms to capacity settings.
Mapped Azure CLI commands
Cosmos DB API for NoSQL commands
direct
az cosmosdb show --name <account> --resource-group <resource-group>
az cosmosdbdiscoverDatabases
az cosmosdb sql database list --account-name <account> --resource-group <resource-group>
az cosmosdb sql databasediscoverDatabases
az cosmosdb sql container list --account-name <account> --resource-group <resource-group> --database-name <database>
az cosmosdb sql containerdiscoverDatabases
az cosmosdb sql container throughput show --account-name <account> --resource-group <resource-group> --database-name <database> --name <container>
az cosmosdb sql container throughputdiscoverDatabases
Architecture context
Cosmos DB API for NoSQL is the native document architecture I expect teams to use when they need JSON items, partitioned scale, SQL-style queries, SDK operations, and change feed integration. Its important decisions happen at container design: partition key, throughput, indexing policy, TTL, unique keys, analytical store, and conflict policy. At the account level, consistency, regions, backup, networking, and identity shape the application envelope. Operators should know which workloads depend on point reads, which run cross-partition queries, and which containers drive RU consumption. This API is flexible, but flexibility punishes vague modeling. Good architecture designs around access patterns first, then proves the design with metrics instead of assuming document storage is automatically cheap or fast.
Security
Security for Cosmos DB API for NoSQL covers account access, data-plane permissions, keys, managed identities where supported, private endpoints, firewall rules, customer-managed keys, and diagnostic evidence. JSON documents often contain nested sensitive fields, so broad query access can expose more data than expected. Teams should classify containers, restrict administrative operations, rotate keys, protect SDK configuration, and avoid putting secrets in app settings without Key Vault controls. Network access should be intentionally designed, not left public by habit. Security reviews should include backup access, change feed consumers, analytics paths, support tools, and proof that denied access is logged. Include access evidence, data classification, and removal procedures in the production checklist.
Cost
Cost for Cosmos DB API for NoSQL is dominated by provisioned or autoscale request units, storage, regions, backup choices, monitoring, and inefficient queries. Point reads with known partition keys are usually cheaper than broad queries, while strong or bounded staleness consistency can raise read cost. Autoscale helps absorb spikes, but maximum RU settings still need budget ownership. Indexing every property is convenient but may not be right for every write-heavy workload. Cost reviews should tie RU consumption to business operations, inspect high-charge queries, track storage growth, and decide whether shared throughput, dedicated throughput, or serverless fits the workload. Tie every cost decision to measured workload behavior and named budget ownership.
Reliability
Reliability for Cosmos DB API for NoSQL depends on region strategy, consistency level, backup policy, partition design, throughput headroom, SDK retries, and how applications handle throttling. Point reads can be very resilient when partition keys are known, while broad cross-partition queries can fail under pressure. Teams should define recovery objectives, restore procedures, failover expectations, and customer impact for each container. Monitor normalized RU, 429 responses, storage growth, logical partition health, latency percentiles, and regional availability. Runbooks should include bad-write recovery, accidental delete response, key rotation, and guidance for pausing noncritical processors during incidents. Include realistic failure drills, owner escalation, and recovery evidence in the runbook.
Performance
Performance for Cosmos DB API for NoSQL comes from matching application access patterns to partition keys, point reads, indexing policy, throughput, consistency, and regional placement. The fastest operations usually know both item id and partition key. Query performance depends on filters, ORDER BY clauses, indexes, result size, and cross-partition work. SDK configuration also matters because retry behavior can hide throttling or amplify it. Teams should load test with real document sizes and key distribution, monitor request charge per operation, and inspect slow query diagnostics. Tuning often starts with data model and query shape, not only more RU. Validate tuning with representative traffic, documented baselines, and user-facing service targets.
Operations
Operationally, Cosmos DB API for NoSQL requires a current inventory of accounts, databases, containers, partition keys, throughput settings, indexing policies, backup mode, regions, applications, and owners. Day-two work includes capacity reviews, query diagnostics, key rotation, SDK upgrades, restore testing, cost allocation, and troubleshooting throttling. Change feed processors, background jobs, and dashboards must be visible because they can consume throughput alongside user traffic. Keep CLI commands, portal screenshots, IaC templates, and runbooks aligned. Good operations make it clear which team can change container settings and which changes require a migration plan. Keep ownership, dashboard links, deployment history, and support escalation steps current.
Common mistakes
Choosing a partition key before validating real access patterns.
Using broad cross-partition queries for high-volume user paths.
Ignoring change feed processors when explaining RU consumption.