Cosmos DB — The Big Picture
Understand the Azure Cosmos DB resource hierarchy, NoSQL API, throughput models, global distribution, SLAs, the emulator, and when to choose free tier vs serverless vs provisioned.
What is Azure Cosmos DB?
Think of Cosmos DB as a planet-scale filing cabinet. You have one account (the office), which holds databases (rooms), which hold containers (filing drawers), which hold items (individual documents). The magic? You can replicate your filing cabinet to offices around the world, and anyone reads from the nearest copy — in single-digit milliseconds.
You pay for how fast the drawers open (throughput in RU/s) and how much paper you store (GB). That’s really it.
Priya’s scenario: choosing Cosmos DB for NovaSaaS
🚀 Priya at NovaSaaS is architecting a multi-tenant SaaS platform serving 200K users across 12 countries. Her requirements:
- Low latency globally — users in Sydney, London, and São Paulo all expect sub-10ms reads
- Elastic scale — Black Friday traffic is 5× normal; she can’t over-provision year-round
- Multi-tenant isolation — each tenant’s data stays logically separated
- 99.99%+ availability — SaaS customers expect always-on
Cosmos DB checks every box. Let’s see how it’s structured.
Resource hierarchy
Every Cosmos DB deployment follows this hierarchy:
Azure Subscription
└── Cosmos DB Account ← endpoint + keys, billing root
└── Database ← logical namespace, optional shared throughput
└── Container ← the "table" — partitioned, indexed, queried
└── Item ← a JSON document (max 2 MB)| Level | What it does | Key facts |
|---|---|---|
| Account | Top-level resource. Holds the endpoint URI and keys. | One account can hold multiple APIs (but you choose one API at creation). |
| Database | Logical grouping of containers. | Optional: you can provision shared throughput at this level. |
| Container | Where data lives. Think of it as a table or collection. | Has a partition key, indexing policy, TTL, unique keys, throughput. |
| Item | A single JSON document. | Max 2 MB per item. Identified by id + partition key value. |
Priya creates one account, one database novasaas, and separate containers per domain — users, projects, billing.
Throughput: database vs container
| Aspect | Database throughput (shared) | Container throughput (dedicated) |
|---|---|---|
| RU/s pool | Shared across all containers in the database | Dedicated to a single container |
| Minimum | 400 RU/s (or 1000 with autoscale) | 400 RU/s (or 1000 with autoscale) |
| Best for | Many containers with variable, low traffic | High-traffic containers that need guaranteed capacity |
| Override | Individual containers can opt out with dedicated throughput | N/A — each container has its own RU/s |
| Cost efficiency | Great when most containers are idle | Better when one container dominates traffic |
Priya uses shared throughput at the database level for dev/test environments (saves cost), and dedicated container throughput in production for her projects container that handles 80% of traffic.
Exam tip: RU/s minimum with shared throughput
When you provision shared throughput, the minimum is 400 RU/s (manual) or 1,000 RU/s (autoscale max). Each container in the shared pool is guaranteed at least 100 RU/s. So if you have 10 containers sharing 1,000 RU/s, each gets at least 100 RU/s — the remaining is distributed on demand.
You can also mix: have some containers on the shared pool and others on dedicated throughput within the same database.
Global distribution and SLAs
Cosmos DB was built for global distribution from day one:
| SLA | Single-region | Multi-region (single-write) | Multi-region (multi-write) |
|---|---|---|---|
| Availability | 99.99% | 99.99% | 99.999% |
| Read latency | < 10 ms at p99 | < 10 ms at p99 | < 10 ms at p99 |
| Write latency | < 10 ms at p99 | < 10 ms at p99 | < 10 ms at p99 |
The 99.999% SLA (five nines) requires multi-region with multi-write enabled. That’s ~5 minutes of downtime per year.
Priya enables multi-region reads across Australia East, UK South, and Brazil South, with writes pinned to Australia East for now. She’ll enable multi-write when her team is ready to handle conflict resolution.
Free tier vs serverless vs provisioned
| Feature | Free tier | Serverless | Provisioned |
|---|---|---|---|
| Throughput | First 1,000 RU/s free (then standard pricing) | Auto-scales per request, billed per RU consumed | You set RU/s (manual or autoscale) |
| Storage | First 25 GB free | Unlimited (within partition limits) | Unlimited (within partition limits) |
| Best for | Dev/test, learning, small apps | Bursty, unpredictable workloads | Production, predictable traffic |
| Global distribution | ✅ Supported | ❌ Single-region only | ✅ Supported |
| Max per subscription | 1 account | Unlimited | Unlimited |
| Idle cost | Free (within limits) | Zero — pay only when used | Minimum RU/s cost always applies |
Ravi’s mistake: Ravi spun up a provisioned account for a weekend hackathon and left 10,000 RU/s running all week. “Why is our Azure bill $400?” Serverless would have cost under $2 for his light traffic.
Exam tip: serverless limitations
Serverless is great for dev/test but has real limitations: single-region only (no global distribution), no dedicated throughput guarantees, and each physical partition supports at most 5,000 RU/s. The exam loves testing whether serverless supports multi-region — it doesn’t. Note: you can now convert a serverless account to provisioned throughput in-place (NoSQL API).
The Cosmos DB emulator
The emulator runs locally on Windows, macOS (Docker), or Linux (Docker). It provides a local endpoint that behaves like the real service:
Endpoint: https://localhost:8081
Key: C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw==That key is the same for every emulator instance — it’s a well-known fixed key, not a secret. The exam may test this.
🎬 Video walkthrough
Flashcards
Knowledge check
Priya needs to choose a throughput model for NovaSaaS production. Her 'projects' container handles 80% of traffic. Which approach is best?
Ravi sets up a Cosmos DB account for a weekend prototype. He expects very light, unpredictable traffic, doesn't need multi-region, and hasn't used a free tier account in this subscription. Which model is cheapest?
Which of these is true about the Cosmos DB emulator?
Next up: Design Data Model — learn how to think access-pattern-first and design containers that match your queries, not your entity-relationship diagrams.