azure-cosmosdb

Core Principle

Choose partition key wisely, design for your access patterns, understand consistency tradeoffs.

Cosmos DB distributes data across partitions. Your partition key choice determines scalability, performance, and cost. Design for even distribution and query efficiency.

---

Cosmos DB APIs

API	Use Case
NoSQL (Core)	Document database, most flexible
MongoDB	MongoDB wire protocol compatible
PostgreSQL	Distributed PostgreSQL (Citus)
Apache Cassandra	Wide-column store
Apache Gremlin	Graph database
Table	Key-value (Azure Table Storage compatible)

This skill focuses on NoSQL (Core) API - the most common choice.

---

Key Concepts

Concept	Description
Container	Collection of items (like a table)
Item	Single document/record (JSON)
Partition Key	Determines data distribution
Logical Partition	Items with same partition key
Physical Partition	Storage unit (max 50GB, 10K RU/s)
RU (Request Unit)	Throughput currency

---

Partition Key Design

Good Partition Keys

// High cardinality, even distribution, used in queries

// E-commerce: userId for user data
{ "id": "order-123", "userId": "user-456", ... }  // PK: /userId

// Multi-tenant: tenantId
{ "id": "doc-1", "tenantId": "tenant-abc", ... }  // PK: /tenantId

// IoT: deviceId for telemetry
{ "id": "reading-1", "deviceId": "device-789", ... }  // PK: /deviceId

// Logs: synthetic key (date + category)
{ "id": "log-1", "partitionKey": "2024-01-15_errors", ... }  // PK: /partitionKey

Hierarchical Partition Keys

// For multi-level distribution (e.g., tenant → user)
// Container created with: /tenantId, /userId

{
  "id": "order-123",
  "tenantId": "acme-corp",
  "userId": "user-456",
  "items": [...]
}

// Query within tenant and user efficiently

Bad Partition Keys

// Avoid:
// - Low cardinality (status, type, boolean)
// - Monotonically increasing (timestamp, auto-increment)
// - Frequently updated fields
// - Fields not used in queries

// Bad: Only 3 values → hot partitions
{ "status": "pending" | "completed" | "cancelled" }

// Bad: All writes go to latest partition
{ "timestamp": "2024-01-15T10:30:00Z" }