🌌 Azure Cosmos DB — Full End-to-End Tutorial¶

🔹 What is Azure Cosmos DB?¶

Azure Cosmos DB is a fully managed, globally distributed NoSQL database designed for:

Massive scale
Low latency
High availability
Automatic replication
Multiple data models

1️⃣ Cosmos DB APIs (VERY IMPORTANT)¶

API	Use Case
SQL API (Core)	Most common, JSON documents
MongoDB API	Mongo-compatible apps
Cassandra API	Wide-column workloads
Table API	Key-value
Gremlin API	Graph data

👉 We use SQL API (Core) — industry standard on Azure.

2️⃣ Core Concepts (Must Understand)¶

🔹 Account¶

Top-level Cosmos DB resource.

🔹 Database¶

Logical grouping of containers.

🔹 Container¶

Like a table (stores JSON documents).

🔹 Item¶

Single JSON document.

🔹 Partition Key¶

How data is distributed and scaled.

🔹 RU/s (Request Units)¶

Cost + performance unit.

3️⃣ Architecture (High Level)¶

App / API / Frontend
        |
        v
Azure Cosmos DB Account
        |
        ├── Database
        │     ├── Container (Partitioned)
        │     │     └── Items (JSON)
        |
        └── Global Replication

4️⃣ Prerequisites¶

az login
az extension add --name cosmosdb

5️⃣ CREATE (Azure CLI)¶

5.1 Create Resource Group¶

az group create \
  --name azure-solution-architect-labs \
  --location centralindia

5.2 Create Cosmos DB Account (SQL API)¶

az cosmosdb create \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing \
  --locations regionName=centralindia failoverPriority=0 \
  --default-consistency-level Session \
  --enable-free-tier true

Explanation¶

Option	Meaning
`--locations`	Region + priority
`Session`	Best balance consistency
Free tier	1000 RU/s + 25 GB free

6️⃣ SHOW / VIEW (CLI)¶

View Account¶

az cosmosdb show \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing

List Accounts¶

az cosmosdb list \
  --resource-group azure-solution-architect-labs \
  --output table

View Keys¶

az cosmosdb keys list \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing

⚠️ Never expose keys in frontend

7️⃣ Create Database & Container¶

7.1 Create Database¶

az cosmosdb sql database create \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --name appdb

7.2 Create Container¶

az cosmosdb sql container create \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --name users \
  --partition-key-path "/userId" \
  --throughput 400

Why `/userId`?¶

Distributes data evenly
Enables horizontal scaling

8️⃣ CRUD Operations (Data)¶

Cosmos DB uses JSON documents.

8.1 Create Item¶

az cosmosdb sql item create \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --container-name users \
  --body '{
    "id": "1",
    "userId": "u100",
    "name": "Yuva",
    "email": "yuva@example.com"
  }'

8.2 View Items¶

az cosmosdb sql item list \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --container-name users

8.3 Query Data (SQL-like)¶

az cosmosdb sql query \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --container-name users \
  --query "SELECT * FROM c WHERE c.userId='u100'"

8.4 Update Item¶

az cosmosdb sql item replace \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --container-name users \
  --item-id "1" \
  --partition-key-value "u100" \
  --body '{
    "id": "1",
    "userId": "u100",
    "name": "Yuva Raj",
    "email": "yuva.raj@example.com"
  }'

8.5 Delete Item¶

az cosmosdb sql item delete \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --container-name users \
  --item-id "1" \
  --partition-key-value "u100"

9️⃣ Security & Access¶

🔹 Keys¶

Primary key
Secondary key (rotation)

🔹 Recommended¶

Use Managed Identity
Store keys in Key Vault

🔐 10️⃣ Network Security¶

az cosmosdb update \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing \
  --enable-public-network false

✔ Private endpoint supported ✔ VNet integration

1️⃣1️⃣ Scaling (RU/s)¶

Increase Throughput¶

az cosmosdb sql container throughput update \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --name users \
  --throughput 1000

Autoscale (Production)¶

--max-throughput 4000

1️⃣2️⃣ Global Replication¶

az cosmosdb update \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing \
  --locations regionName=centralindia failoverPriority=0 \
              regionName=westus failoverPriority=1

✔ Multi-region writes ✔ Automatic failover

1️⃣3️⃣ Backup & Restore¶

Backup Modes¶

Mode	Description
Periodic	Default
Continuous	Point-in-time restore

az cosmosdb update \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing \
  --backup-policy-type Continuous

1️⃣4️⃣ Monitoring¶

RU consumption
Throttling (429)
Latency
Storage

Tools:

Azure Monitor
Metrics
Alerts

1️⃣5️⃣ DELETE (Cleanup)¶

Delete Container¶

az cosmosdb sql container delete \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --database-name appdb \
  --name users

Delete Database¶

az cosmosdb sql database delete \
  --account-name cosmosdb-testing \
  --resource-group azure-solution-architect-labs \
  --name appdb

Delete Cosmos DB Account¶

az cosmosdb delete \
  --resource-group azure-solution-architect-labs \
  --name cosmosdb-testing

🧠 FINAL SUMMARY (VERY IMPORTANT)¶

Account
 └── Database
      └── Container
           └── Items (JSON)

✔ Fully managed ✔ Auto scale ✔ Global distribution ✔ Enterprise grade