What is Azure Cosmos DB?

Azure Cosmos DB is Microsoft's globally distributed, multi-model database service designed for high availability, scalability, and low latency. It is a fully managed NoSQL database platform that enables you to elastically and independently scale throughput and storage across any number of Azure regions.

More details: Azure Cosmos DB | Microsoft Learn

Key Highlights:

Globally distributed: Data can be replicated across multiple regions.
Multi-model: Supports multiple data models like key-value, document, graph, and column-family.
Multi-API support: You can interact with Cosmos DB using different APIs, each tailored to a specific data model.

Supported APIs

Azure Cosmos DB supports the following APIs:

API	Description	Common Use Cases
Core (SQL) API	JSON document database using SQL-like syntax	General-purpose NoSQL, web and mobile apps
MongoDB API	Wire-compatible with MongoDB	Applications already using MongoDB
Cassandra API	Column-family data model	High-throughput workloads, time-series data
Gremlin API	Graph database API	Social networks, recommendation engines
Table API	Key-value store (Azure Table Storage-compatible)	Simple key-value storage use cases

More details: Choose an API in Azure Cosmos DB | Microsoft Learn

For this article, we focus on the Core (SQL) API, also known as NoSQL API.

Core Components of Cosmos DB SDK

When using Cosmos DB with the official SDK (available in .NET, Java, Python, JavaScript, and more), you typically interact with these components:

CosmosClient: Entry point to the service.
Database: A logical container for collections (containers).
Container: Holds your JSON documents. Equivalent to a collection or table.
Item: A single document in a container.

var client = new CosmosClient(connectionString);
var container = client.GetContainer("MyDatabase", "MyContainer");

More details: Azure Cosmos DB SDK | Microsoft Learn

Partition Key and Partitioning Strategy

What is a Partition Key?

A partition key is a property in your document that Cosmos DB uses to distribute data across physical partitions. It's critical for performance and scalability.

Why is it Important?

Ensures scalability
Enables high availability
Optimizes cost and throughput

Good Partition Key Characteristics:

High cardinality
Even data distribution
Predictable access patterns

Example:

{
  "id": "order123",
  "customerId": "cust001",
  "region": "WestUS",
  "orderTotal": 42.99
}

Partition Key = /customerId

Tip: Avoid keys with low cardinality like region or constant values.

Core Features of Cosmos DB

1. Global Distribution

Enable multi-region writes or reads
Automatic failover between regions
Low-latency reads and writes worldwide

2. Multi-Model and Multi-API

Store and query document, key-value, graph, and column data

3. Guaranteed SLAs

99.999% availability
<10 ms reads, <15 ms writes
99.999% consistency

4. Five Consistency Levels

Strong
Bounded Staleness
Session (default)
Consistent Prefix
Eventual

5. Automatic Indexing

All data is indexed by default
Customize indexing policies for performance or storage optimization

6. Time-to-Live (TTL)

Automatically delete documents after a defined lifetime
Useful for session tokens, logs, telemetry data

Advanced Capabilities

1. Transactions and Batching

Use TransactionalBatch to perform atomic operations on items within the same partition key

TransactionalBatch batch = container.CreateTransactionalBatch(new PartitionKey("cust001"));
batch.CreateItem(newOrder).ReplaceItem("order123", updatedOrder);
await batch.ExecuteAsync();

2. Optimistic Concurrency (ETag)

Use ETags to handle concurrent updates

3. Change Feed

Subscribe to changes in your data for real-time processing
Ideal for event sourcing, real-time analytics

4. Geo-replication

Add regions easily
Active-active (multi-master) or active-passive setup
Conflict resolution policies available

Limitations & Considerations

Aspect	Limitation or Note
Query Language	No JOINs across containers
Partitioning	All operations in a batch must share same partition key
Throughput	RUs must be managed carefully to avoid throttling
Cost	RU/s-based pricing; idle workloads still cost money
TTL	TTL deletes are soft deletes only (lag in actual removal)
SDK Limits	Max payload size (2MB per item)

When to Use Cosmos DB

Need for low-latency global access
Variable or unstructured data
Elastic scale requirements
Serverless architecture integration

When not to Use

Complex multi-container JOINs
Large analytical workloads (prefer Azure Synapse or SQL DW)
Strict schema enforcement needs

Visualization

Here is a high-level visualization of Cosmos DB Core API structure:

+-------------------+
|   CosmosClient    |
+-------------------+
         |
         v
+-------------------+
|     Database      |
+-------------------+
         |
         v
+-------------------+
|     Container     |<--- Partition Key
+-------------------+
         |
         v
+-------------------+
|       Item        |
+-------------------+

Final Thoughts

Azure Cosmos DB is a powerful, flexible, and globally scalable NoSQL solution - but it requires a solid understanding of partitioning, consistency models, and throughput management to use effectively. With careful design, it's a great fit for modern cloud-native applications.

Follow for more deep dives on Cosmos DB and other cloud technologies. We'll soon explore advanced features of the Cosmos DB in detail - stay tuned.