Introduction to Azure Cosmos DB

Azure Cosmos DB is a globally distributed, multi-model database service designed for mission-critical applications. It guarantees single-digit millisecond latency at the 99th percentile, offers 99.999% availability with multi-region writes, and scales elastically without limits. This lesson introduces Cosmos DB's core concepts, architecture, and use cases.

---

What Is Cosmos DB?

Cosmos DB is a planet-scale NoSQL database. Unlike traditional databases that run in a single data centre, Cosmos DB is designed from the ground up for global distribution — your data can be replicated to any number of Azure regions, and users worldwide get fast, local access.

Key Differentiators

Feature	Detail
Global distribution	Replicate data to any Azure region with a few clicks
Multi-model	Supports multiple APIs and data models (document, key-value, graph, wide-column)
Single-digit ms latency	Guaranteed < 10ms for reads and writes at the 99th percentile
99.999% availability	With multi-region writes enabled
Elastic scale	Throughput and storage scale independently, with no upper limit
Schema-free	No fixed schema — each item can have different properties
Turnkey global distribution	Add or remove regions without downtime

---

Core Architecture

Resource Model

Cosmos DB organises data in a hierarchy:

Azure Subscription
  |
  |-- Cosmos DB Account (choose API at creation time)
        |
        |-- Database (namespace)
              |
              |-- Container (collection / table / graph)
                    |
                    |-- Items (documents / rows / nodes / edges)

Concept	Relational Equivalent	Description
Account	Server	Top-level resource; defines API, regions, and consistency
Database	Database	Logical namespace; can provision shared throughput
Container	Table	Unit of scalability; holds items; requires a partition key
Item	Row	Individual data record (JSON document in the NoSQL API)

Partition Key

The partition key is the most important design decision in Cosmos DB. It determines how data is distributed across physical partitions:

Container: Orders
Partition Key: /customerId

Physical Partition 1: [customerId: "c001", "c002", "c003"]
Physical Partition 2: [customerId: "c004", "c005", "c006"]
Physical Partition 3: [customerId: "c007", "c008", "c009"]

A good partition key has:

• High cardinality — many distinct values (e.g., userId, orderId)
• Even distribution — each partition key value stores roughly the same amount of data
• Frequently used in queries — most queries include the partition key in the WHERE clause

A logical partition (all items with the same partition key value) has a maximum size of 20 GB. Physical partitions hold one or more logical partitions and are managed automatically by Cosmos DB.

---

Creating a Cosmos DB Account

az cosmosdb create \
  --resource-group rg-demo \
  --name my-cosmos-account \
  --kind GlobalDocumentDB \
  --locations regionName=uksouth failoverPriority=0 \
  --locations regionName=northeurope failoverPriority=1 \
  --default-consistency-level Session

At creation time you choose:

1. API — determines the data model and client SDK (cannot be changed later)
2. Regions — initial write and read regions
3. Default consistency level — can be relaxed per request
4. Capacity mode — provisioned or serverless

---

Throughput: Request Units (RUs)

Cosmos DB measures throughput in Request Units per second (RU/s):