Azure Cosmos DB Overview

What makes Cosmos DB different

Traditional databases are designed around a single location. You put them in a datacenter, and everything connects to that datacenter. When users are far away, they wait. When traffic spikes, you scale up a bigger machine (vertical scaling).

Cosmos DB inverts this model:

• Multi-region by design — add regions in the Portal or CLI and data is replicated there automatically, usually within minutes
• Horizontal scale — throughput and storage scale out across physical partitions, not up to a bigger machine
• Multiple APIs — the same underlying engine supports SQL (NoSQL), MongoDB, Cassandra, Gremlin (graph), and Table APIs
• Tunable consistency — you choose the trade-off between consistency and performance for your workload

The trade-off: Cosmos DB does not support multi-table JOIN queries, stored procedures with complex transactions spanning many records, or the rich analytics capabilities of a data warehouse. It’s optimized for transactional workloads with known access patterns.

Choosing your API

When you create a Cosmos DB account, you choose an API. The API determines how your application talks to Cosmos DB.

For new applications, the NoSQL API (also called the SQL API or Core API) is the right default. It has the best SDK support, the most documentation, and access to all Cosmos DB features. The MongoDB API is a close second if your team already knows MongoDB and you want to minimize learning curve.

Consistency levels

When data is replicated across multiple regions, there’s an inherent tension: if you write data in East US and immediately read it in Europe, might you see the old value before the new one has propagated? Cosmos DB gives you five levels to control this trade-off:

Session consistency — the default — is the right choice for most web applications. Within a user’s session, reads always reflect that user’s own writes. Other users’ recent writes might not be visible immediately, which is usually acceptable.

Creating a Cosmos DB account with Azure CLI

# Create a Cosmos DB account with the NoSQL API
az cosmosdb create \
  --resource-group my-storage-rg \
  --name my-cosmos-account \
  --kind GlobalDocumentDB \
  --default-consistency-level Session \
  --locations regionName=eastus failoverPriority=0 isZoneRedundant=True \
  --locations regionName=westus failoverPriority=1 isZoneRedundant=False

# Add a second read region later
az cosmosdb update \
  --resource-group my-storage-rg \
  --name my-cosmos-account \
  --locations regionName=eastus failoverPriority=0 isZoneRedundant=True \
  --locations regionName=westus failoverPriority=1 isZoneRedundant=False \
  --locations regionName=northeurope failoverPriority=2 isZoneRedundant=False

# Create a database
az cosmosdb sql database create \
  --resource-group my-storage-rg \
  --account-name my-cosmos-account \
  --name myapp-db

# Create a container with 400 RU/s provisioned throughput
az cosmosdb sql container create \
  --resource-group my-storage-rg \
  --account-name my-cosmos-account \
  --database-name myapp-db \
  --name products \
  --partition-key-path "/categoryId" \
  --throughput 400

# View the account details
az cosmosdb show \
  --resource-group my-storage-rg \
  --name my-cosmos-account \
  --output json

Throughput models: provisioned vs serverless

Cosmos DB has two ways to pay for compute:

• Provisioned throughput — you specify a fixed number of RU/s (minimum 400 per container). You pay whether you use it or not. Best for predictable production traffic. You can also use autoscale (400-4000 RU/s, scaling automatically based on load).
• Serverless — you pay per RU consumed, no minimum. Ideal for development, testing, and bursty low-traffic workloads. Cannot be used with multi-region writes.

# Create a serverless account
az cosmosdb create \
  --resource-group my-storage-rg \
  --name my-cosmos-serverless \
  --kind GlobalDocumentDB \
  --capabilities EnableServerless

# Create a container with autoscale throughput (400-4000 RU/s)
az cosmosdb sql container create \
  --resource-group my-storage-rg \
  --account-name my-cosmos-account \
  --database-name myapp-db \
  --name orders \
  --partition-key-path "/userId" \
  --max-throughput 4000