Cosmos DB in 5 Minutes

You open the Azure portal, click + Cosmos DB, fill in three fields, and 90 seconds later you have a globally replicated, infinitely-scaling, multi-model database. The same one Microsoft uses to back parts of Xbox Live, LinkedIn, and Skype. So what’s actually inside that turnkey button?

This lesson is the panoramic view. The other 19 lessons drill into pieces; here we just look at the whole machine.

The five APIs

Cosmos DB is one storage engine with five wire-protocol front-ends:

You pick one per account at creation time. You can’t mix — but you can run multiple Cosmos accounts side-by-side.

The rest of this course assumes the SQL (Core) API unless explicitly noted. It’s the API Microsoft is investing in most heavily, and it’s what you’d pick for any new application.

Three nouns to know

Cosmos’s hierarchy is shorter than you’d expect:

Account                          (one per region group, has its own endpoint URL)
  └── Database                   (logical namespace — like a Postgres database)
      └── Container              (the unit of throughput + partitioning — like a table)
          └── Item               (a JSON document)

That’s it. No tables-of-tables, no schemas, no namespaces inside namespaces. Container is the unit you reason about. Every container has:

• A partition key — a JSON path you choose, e.g. /tenantId or /userId. This is the single most consequential decision (lesson V02 is dedicated to it).
• A throughput setting — RUs per second, either provisioned (fixed) or autoscale (4× burst capacity).
• An indexing policy — by default, every path is indexed. You opt out for cost (lesson V07).
• A TTL setting — optional auto-expiry on items.

Partitioning, in one paragraph

Cosmos hashes your partition-key value into one of ~256 logical partitions, then maps logical partitions onto physical partitions (the actual VMs). Each physical partition holds up to 50 GB and 10,000 RU/s. When a logical partition outgrows that, Cosmos automatically splits the physical partition behind your back — no downtime, no migration.

What this means for you: all documents sharing a partition-key value live together and can be queried/transacted atomically. Crossing partitions costs more RUs and breaks transactions. Picking the wrong key — /status (only 3 distinct values) or /customerId for one giant customer — creates hot partitions that throttle while everything else sits idle.

The currency: Request Units

Cosmos charges in RUs, not IOPS or seconds. Every operation costs a deterministic number of RUs:

You provision RU/s at the container (or database) level. Hit the limit, requests get HTTP 429 and the SDK retries with backoff. Lesson V09 dives in.

The big idea: RUs make cost predictable. You can model a workload’s cost on a napkin: (reads × 1) + (writes × 6) + (queries × 8). No surprise IOPS bill at the end of the month.

Five consistency levels

This is the headline feature. Cosmos lets you choose, per request, where on the consistency spectrum you want to sit:

You set a default at the account level, and override per request when needed. Stronger = slower and more expensive in RUs. Lesson V04 walks through each with a concrete scenario.

Multi-region writes — the magic checkbox

The feature that genuinely sets Cosmos apart: turnkey multi-master.

Add a region in the portal → that region becomes a peer write endpoint. Your app, using the SDK with PreferredLocations = ["West US 2", "East US"], automatically writes to the nearest region. Conflicts resolve by:

• Last-write-wins (default) using a server-side timestamp
• Custom merge via a stored procedure you provide

Other databases either don’t do multi-master at all, or do it with painful caveats (eventual-only, no transactions, manual conflict files, etc.). Cosmos makes it a checkbox.

The trade-off is real: multi-region writes pin you to weaker-than-strong consistency (you can pick session or weaker globally). And cross-region writes cost more RUs than single-region.

What’s next in this course

You’ve now seen the whole machine at altitude. The next 14 engineer-course lessons drill into the moving parts:

1. V02 — Partitioning (the #1 decision)
2. V03 — Data Modeling (embed vs reference)
3. V04 — Consistency Levels (the five knobs in detail)
4. V05 — CRUD, Batch & Transactions
5. V06–V07 — Querying & Indexing
6. V08 — SDK Best Practices
7. V09 — Request Units & Cost
8. V10 — Monitoring & Troubleshooting
9. V11 — Change Feed
10. V12 — Global Distribution
11. V13 — Security & Access
12. V14 — Vector Search & AI
13. V15 — Local Dev & CI/CD

If you want the underlying theory first — replication algorithms, storage engines, partitioning math — start with the Foundations track (F1–F5). Otherwise, jump into V02 next; partition keys are where most production pain originates.