Azure Cosmos DB Guide
Azure Cosmos DB is a fully managed, globally distributed NoSQL database service designed for cloud‑native applications that demand single‑digit millisecond latency, elastic scalability, and multi‑region availability. Unlike traditional relational databases that scale vertically and rely on a single primary instance, Cosmos DB uses a horizontally scalable architecture that replicates data across multiple regions, allowing you to serve users wherever they are with low latency.
It is a multi‑model database, meaning you can interact with your data using the NoSQL (SQL) API, MongoDB API, Cassandra API, Gremlin (graph) API, or Table API. Under the hood, however, Cosmos DB runs on its own internal data engine; it is not a managed instance of any open‑source database. This architecture gives it unique capabilities—such as tunable consistency levels and automatic indexing—that set it apart from both traditional relational databases and self‑hosted NoSQL engines.
Cosmos DB is not a drop‑in replacement for a relational database. It does not support arbitrary joins, server‑side transactions across documents, or rigid schema enforcement in the same way SQL Server or PostgreSQL do. Instead, it rewards applications that model data around access patterns, embrace denormalization, and design for horizontal scale from the start.
When Should You Use Azure Cosmos DB?
Cosmos DB excels in workloads that have one or more of the following characteristics:
- Global distribution – You need to replicate data to multiple Azure regions and serve users with low latency, perhaps even with multi‑region writes.
- Flexible or evolving schemas – Your data model changes frequently, contains heterogeneous entities, or benefits from a schema‑less approach.
- Elastic scalability – Traffic is unpredictable, and you need to scale throughput up or down without downtime.
- Low‑latency requirements – Guaranteed single‑digit millisecond read and write latencies at the 99th percentile.
- High write volumes – Applications like IoT telemetry, gaming, and event sourcing that generate massive write throughput.
Common scenarios include global SaaS platforms, mobile app backends, gaming leaderboards, IoT data pipelines, product catalogs, user profile stores, and AI applications with dynamic metadata.
Cosmos DB is not the best choice when:
- Your workload requires complex relational joins, stored procedures that span tables, or server‑side transactional logic across multiple entities (use Azure SQL Database or PostgreSQL).
- You are migrating a legacy application that assumes relational semantics and cannot be refactored.
- You need a traditional data warehouse with star schemas and analytical processing (use Azure Synapse or Microsoft Fabric).
- Your data is strictly tabular with little need for schema flexibility or global distribution.
Azure Cosmos DB Architecture
Cosmos DB’s architecture is built around three core principles: horizontal partitioning, automatic replication, and tunable consistency.
- Logical partitions group data by a partition key. Each logical partition can scale to 20 GB and is the unit of horizontal distribution.
- Physical partitions are the underlying compute + storage units that host one or more logical partitions. As your data grows, Cosmos DB transparently splits and moves logical partitions across physical partitions.
- Replication occurs automatically across all configured regions. For write regions, the primary replica receives writes and asynchronously or synchronously replicates them to secondaries, depending on the consistency level.
- Storage engine is based on a write‑optimized, log‑structured, and automatically indexed store. Every item is indexed by default, but you can customize the indexing policy.
Because Cosmos DB abstracts physical partitions, you never directly manage shards or nodes. The service handles scaling, rebalancing, and failover.
Core Concepts
Before diving deeper, it helps to understand the fundamental building blocks:
- Database – A management unit that groups containers. You can provision throughput at the database level (shared among containers) or at the container level (dedicated).
- Container – A schema‑agnostic collection of items (documents, rows, graphs). Containers hold your data and define the partition key and indexing policy.
- Item (document) – An individual record in a container, typically a JSON document. Items are the units of read, write, and query operations.
- Partition key – The property used to group items into logical partitions. This is the single most important design decision in Cosmos DB.
- Request Unit (RU) – An abstract currency that represents the compute, memory, and I/O required for an operation. Reads, writes, and queries consume RUs.
- Throughput – Measured in RU/s, provisioned at either the database or container level. You can choose manual provisioned throughput, autoscale, or serverless.
- Region – An Azure data center location where Cosmos DB replicates your data. You can add or remove regions dynamically.
Supported APIs
Cosmos DB exposes multiple APIs that translate requests into the internal data model, allowing you to use familiar SDKs.
| API | Data Model | Primary Use | Limitations |
|---|---|---|---|
| NoSQL (SQL API) | JSON documents with a SQL‑like query language | New cloud‑native applications; most feature‑rich API | Not compatible with MongoDB/Cassandra clients |
| MongoDB API | BSON documents; supports most MongoDB wire protocol features | Migrating existing MongoDB applications | Not all MongoDB operations are supported; check compatibility |
| Cassandra API | Wide‑column store with CQL | Migrating Cassandra workloads | Limited to subset of Cassandra features; eventual consistency model |
| Gremlin (Graph) API | Vertices and edges; Apache TinkerPop Gremlin traversal language | Graph‑based applications like social networks, recommendation engines | Throughput limits differ; not suitable for massive real‑time graph analytics |
| Table API | Key‑value store; compatible with Azure Table Storage | Migrating from Azure Table Storage | Limited query capabilities; superseded by NoSQL API for most scenarios |
Recommendation: For new applications, choose the NoSQL (SQL) API. It provides the richest feature set, the best performance, and the most straightforward path to leverage Cosmos DB’s full capabilities. Only use other APIs when you are migrating an existing application that cannot be refactored.
Global Distribution
One of Cosmos DB’s distinguishing capabilities is the ability to replicate data to any number of Azure regions with a few clicks.
- Multi‑region writes allow you to accept writes in multiple regions simultaneously, reducing latency for worldwide users. This comes with trade‑offs: conflicts are handled using a last‑writer‑wins (LWW) policy or custom conflict resolution, and eventual consistency in multi‑write mode has different behavior than single‑write mode.
- Single‑region writes (the more common configuration) designate one region as the primary for writes. Reads can be served from any replica, depending on consistency level.
- Failover priorities determine which region becomes the new write region during an outage. You can configure automatic or manual failover.
Trade‑offs:
- Multi‑region writes can reduce latency but introduce conflict resolution complexity. Start with single‑region writes and add regions as read replicas; only move to multi‑region writes when you have a clear need and understand the consistency implications.
- Adding regions increases cost (each region’s provisioned throughput is billed) and can slightly increase write latency due to replication overhead, depending on consistency.
- Not every application needs global distribution. Use it when you have users in distant geographies who require low‑latency data access.
Consistency Models
Cosmos DB offers five well‑defined consistency levels, a unique capability among cloud databases. This allows you to make explicit trade‑offs between consistency, latency, availability, and throughput.
| Level | Description | Latency | Availability | Use Case |
|---|---|---|---|---|
| Strong | Reads always return the most recent committed write; linearizability | Highest write latency | Lower availability during outages | Financial transactions, ledger systems |
| Bounded Staleness | Reads may lag writes by a configurable time window or version count | Slightly lower latency than Strong | High | Multi‑player games, collaboration tools |
| Session (default) | Strong consistency within a client session; eventual outside sessions | Low write latency | High | Most web/mobile applications |
| Consistent Prefix | Reads never see out‑of‑order writes; eventual consistency with order | Low latency | High | Chat applications, event logging |
| Eventual | No ordering guarantees; eventually all replicas converge | Lowest latency | Highest availability | Social media feeds, content caching |
How to choose:
- Session is the recommended default for most cloud‑native applications. It provides strong consistency for a single client’s own writes—a common requirement—while offering high performance and availability.
- Use Strong only when business requirements demand it, and understand the latency and cost implications.
- Use Bounded Staleness when you need a quantifiable staleness guarantee, such as for global collaborative tools.
- Use Consistent Prefix when order of updates matters but immediate consistency does not.
- Use Eventual for the highest throughput and availability, often in IoT ingestion or caching scenarios.
Important: Consistency levels are per‑request, so you can mix and match within the same application. For example, user profile writes can be Strong while feed reads are Eventual.
Partitioning
Partition key design is the foundation of a successful Cosmos DB implementation. It determines how data is distributed across logical partitions, which in turn impacts scalability, throughput, and cost.
How Partitioning Works
- A logical partition is a set of items that share the same partition key value. For example, if the partition key is
/userId, all documents with a givenuserIdbelong to the same logical partition. - A physical partition is a compute + storage unit that hosts one or more logical partitions. Cosmos DB automatically manages physical partitions, splitting and rebalancing them as data grows.
- All items within a logical partition are guaranteed to be on the same physical partition, which enables single‑partition queries and transactions.
Good Partition Keys
A good partition key has the following properties:
- High cardinality – Many distinct values (e.g.,
userId,deviceId,orderId) so data is spread evenly. - Even distribution of reads and writes – The workload is balanced across logical partitions.
- Frequently used in queries – Queries that filter on the partition key are the most efficient and cheapest.
Poor Partition Keys
- Low cardinality – Keys like
status,type, orcountrylead to a few large, unbalanced partitions. - Timestamp – Using creation time as the partition key creates a hot partition for current data while older data sits idle.
- Constant value – A partition key that is the same for all items defeats the purpose of partitioning and limits the logical partition’s 20 GB storage cap.
Cross‑partition Queries
Queries that do not include the partition key must be fanned out across all physical partitions. These cross‑partition queries consume more RUs and have higher latency. While Cosmos DB handles them well, you should design your application to minimize them by structuring queries around the partition key.
Examples:
- If you partition by
/userId, a query to get all orders for a user is a single‑partition operation. A query to get all orders in a date range across users is a cross‑partition query. - Pre‑compute aggregates or maintain separate lookup containers when you need efficient cross‑partition access patterns.
Throughput and Request Units (RU)
Cosmos DB abstracts compute resources into Request Units (RU). Every operation—read, write, query, stored procedure—consumes RUs, which represent a blend of CPU, memory, and I/O. You provision throughput in RU/s, and Cosmos DB throttles requests when they exceed provisioned capacity (returning HTTP 429).
Provisioning Models
- Provisioned throughput (manual) – You set a fixed RU/s at the container or database level. Predictable cost, ideal for steady workloads.
- Autoscale – You set a maximum RU/s, and Cosmos DB scales between 10% and 100% of that maximum based on demand. Best for variable workloads; you pay only for what you use, but it requires proper tuning of the max value.
- Serverless – Pay per‑operation, no provisioned throughput. Ideal for sporadic, low‑volume workloads or development/test environments. Not suitable for production scenarios requiring guaranteed throughput.
RU Consumption Factors
- Point reads (by ID and partition key) are the cheapest: 1 RU for a 1 KB item.
- Writes are heavier: ~5 RU for a 1 KB insert/replace.
- Queries depend on the complexity, number of results, and whether they are single‑partition or cross‑partition. A single‑partition filter that returns a few items is cheap; a cross‑partition scan can be expensive.
- Indexing overhead is included in write RUs. Customizing the indexing policy can reduce write costs.
Data Modeling
NoSQL data modeling differs fundamentally from relational modeling. In Cosmos DB, you model data based on query patterns, not entity‑relationship diagrams.
Embedding vs Referencing
- Embed related data that is always accessed together. For example, a customer document can embed their address and a list of recent orders, avoiding joins.
- Reference data when it is large, independently accessed, or shared across multiple entities. Use separate containers and a lightweight lookup pattern (e.g., storing the referenced item’s ID).
Trade‑offs: Embedding reduces read complexity but can lead to large documents and hot partitions. Referencing adds client‑side work (multiple reads) but keeps documents small and denormalized.
Other Principles
- Denormalize aggressively. Cosmos DB does not support joins across containers. Duplicate data where needed to satisfy query patterns.
- Keep document sizes under 2 MB (the maximum item size). Large documents slow down reads and writes.
- Use arrays and nested objects to represent one‑to‑many relationships that are bounded in size.
- Model for OLTP, not analytics. If you need heavy analytical processing, replicate data to Azure Synapse or use the Cosmos DB analytical store (if enabled).
High Availability
Cosmos DB provides built‑in high availability:
- Within a region: Data is replicated across multiple fault and update domains. The SLA guarantees 99.99% availability for single‑region writes and reads.
- Multi‑region: With multi‑region writes, the SLA increases to 99.999% read and write availability. Cosmos DB automatically fails over writes if the primary region becomes unavailable (if automatic failover is configured).
- RPO and RTO: With multi‑region writes and automatic failover, RPO can be 0 for data loss (depending on consistency level) and RTO is the time to redirect writes, typically under 5 minutes.
- Availability zones: You can enable zone redundancy within a region to protect against data center failures.
Operational advice: Test failover regularly. Validate that your application handles HTTP 429 responses and connection timeouts gracefully when a failover occurs.
Security
- Authentication: Use Microsoft Entra ID for management plane (Azure RBAC) and access keys or resource tokens for data plane. Prefer Entra ID integration with managed identities for production workloads.
- Network isolation: Use Private Link to give Cosmos DB a private IP in your virtual network. Firewall rules can restrict access to specific IP ranges or Azure services.
- Encryption: All data is encrypted at rest (by default) and in transit (TLS 1.2+). Customer‑managed keys are supported for encryption at rest.
- RBAC: Cosmos DB has built‑in roles (reader, contributor, etc.) for fine‑grained access control at the account and container level.
Best practices: Never expose your Cosmos DB account to the public internet. Use Private Link and disable public access for production. Rotate access keys and prefer managed identities.
Performance Optimization
- Partition key first: The most impactful optimization. Avoid hot partitions and design queries that filter on the partition key.
- Single‑partition queries: Prefer point reads (
ReadItemAsyncby ID and partition key) over queries whenever possible. - Selective indexing: By default, every property is indexed. For large items with rarely queried fields, exclude those paths from indexing to reduce write RU cost and storage.
- TTL (Time‑to‑Live): Set TTL at the container or item level to automatically delete old data and control storage costs.
- Batch operations: Use stored procedures or transactional batch operations within the same logical partition for multi‑item updates.
- Connection mode: Use Direct mode (default in most SDKs) over Gateway mode for lower latency. Configure the SDK properly (e.g., connection pool size,
MaxConcurrency). - SDK optimization: Keep the SDK updated. Use the latest version and tune the
ApplicationRegionpreference, retry policies, andMaxRetryAttemptsOnThrottledRequests.
Monitoring
Use Azure Monitor to track critical metrics:
- Total Request Units (RU/s) consumption vs provisioned capacity. Set alerts when usage exceeds 80% of provisioned.
- Throttled requests (HTTP 429) – Indicates insufficient throughput. Consider autoscale or higher RU/s.
- Latency (P50, P99) – Monitor read and write latency per region.
- Service availability – Track whether the database is reachable.
- Storage utilization – Logical partition size is capped at 20 GB; monitor for partitions nearing the limit.
- Replication health – For multi‑region accounts, ensure replication lag is acceptable.
Diagnostic logs can be sent to Log Analytics or Storage for deeper investigation.
Cost Optimization
- Right‑size throughput: Use autoscale for variable workloads. For steady workloads, use manual provisioned throughput with reserved capacity discounts (up to 65%).
- Serverless is cost‑effective for low‑traffic, intermittent scenarios but not for production consistency.
- Partition key design: Avoid hot partitions that force over‑provisioning of RU/s.
- Indexing strategy: Exclude paths that you never query to save on write RUs and storage.
- TTL: Automatically delete data you don’t need to keep.
- Data retention in multi‑region: Each region adds cost. Only add regions that serve active users or satisfy compliance needs.
- Consistency level: Strong consistency consumes more RUs and adds latency; use only when necessary.
Azure Cosmos DB vs Other Azure Database Services
| Service | Best For |
|---|---|
| Azure Cosmos DB | Globally distributed NoSQL, low‑latency, flexible schemas, horizontal scale |
| Azure SQL Database | Relational OLTP with rich T‑SQL, joins, and ACID transactions |
| Azure SQL Managed Instance | Lift‑and‑shift SQL Server migrations requiring instance‑level compatibility |
| Azure Database for PostgreSQL | PostgreSQL‑based applications with advanced querying and extension support |
| Azure Cache for Redis | Sub‑millisecond caching layer, session state, pub/sub |
| Microsoft Fabric | Unified analytics and data warehousing over large historical datasets |
Choose Cosmos DB when your application is born in the cloud and designed for horizontal scale and global reach. Choose Azure SQL or PostgreSQL when you need a relational engine with strong transactional and join support.
Common Use Cases
Global SaaS Platform
Deploy Cosmos DB in multiple regions with multi‑region writes. Tenant data is partitioned by tenantId, and each tenant’s documents reside in a single logical partition. This enables strong consistency for a tenant’s own data and low latency worldwide.
Gaming Leaderboard
Use the NoSQL API with a partition key of gameMode and a secondary key of userId. Store scores as items, and use a sorted set‑like approach (or an external cache) for real‑time leaderboard queries. Autoscale handles traffic spikes during events.
IoT Telemetry
Ingest millions of events per second. Partition by deviceId to distribute data evenly. Use TTL to automatically age out old telemetry. Stream changes to Azure Functions or Event Hubs for real‑time processing.
E‑commerce Catalog
Partition by productCategory. Embed product variants as nested arrays. Use a separate container for inventory counts, partitioned by sku. Offload search functionality to Azure AI Search.
AI Applications
Store conversation history, embedding metadata, or model‑generated content. Partition by userId or sessionId. Use serverless or autoscale for unpredictable inference‑driven workloads. Integrate with Azure OpenAI for retrieval‑augmented generation patterns where Cosmos DB acts as the metadata store.
Common Mistakes
- Poor partition key selection – Leads to hot partitions, storage limits, and throttling. It is the #1 cause of performance and scaling issues.
- Modeling Cosmos DB like a relational database – Using many containers, trying to normalize data, or expecting joins. Embrace denormalization and embed related data.
- Cross‑partition queries everywhere – A sign that the partition key doesn’t match query patterns. Redesign the key or add a secondary lookup container.
- Over‑indexing – Indexing everything by default is fine for most cases, but heavy write workloads may benefit from custom indexing policies.
- Ignoring RU costs – A single unoptimized query can consume thousands of RUs. Monitor and tune.
- Choosing Strong consistency unnecessarily – It increases write latency and cost. Session consistency satisfies most user‑facing apps.
- Using one container for unrelated workloads – Can cause hot partitions and make cost attribution difficult. Isolate different access patterns into separate containers.
- Ignoring TTL – Old data accumulates, increasing storage and backup costs.
- Not planning global replication – Adding regions reactively is more complex than designing for global distribution up front.
Architecture Best Practices
- Design the partition key first. It’s the hardest thing to change later.
- Model data around query patterns, not normalized entities.
- Prefer Session consistency for web and mobile apps unless stronger guarantees are required.
- Minimize cross‑partition queries by choosing a partition key that appears in your most frequent queries.
- Monitor RU consumption and set alerts on throttling.
- Use autoscale when traffic is unpredictable; use provisioned with reserved capacity for steady workloads.
- Secure access with Microsoft Entra ID and Private Link. Disable public access.
- Test multi‑region failover and validate application behavior under region‑loss scenarios.
- Review indexing policies periodically and exclude paths that are never queried.
- Optimize before increasing throughput: check query design, indexing, and partition key before scaling RU/s.
Related Azure Services
- Azure App Service / Functions / AKS – Compute platforms hosting applications that consume Cosmos DB.
- Azure Event Grid – React to changes in Cosmos DB containers via change feed.
- Azure Service Bus – Decouple downstream processing of Cosmos DB change events.
- Azure API Management – Expose Cosmos DB data through managed APIs.
- Azure Cache for Redis – Cache frequently accessed items to reduce RU consumption.
- Azure AI Search – Offload full‑text and vector search from Cosmos DB.
- Azure Monitor – Centralized monitoring and alerting for Cosmos DB metrics.
- Azure Key Vault – Store access keys and connection strings securely.