Azure Cosmos DB - Getting Started Guide

Microsoft gives you five APIs, but they're not all created equal.

I've deployed every single one in production and lived through the pain. Here's what nobody tells you:

The APIs Ranked by How Much They'll Ruin Your Week

NoSQL API (Core SQL):

Just fucking use this one. It's Microsoft's favorite child and gets new features first. If you know SQL, the learning curve isn't terrible. Gets stored procedures, triggers, and somehow burns through RUs more efficiently than the others. When that weird connection pooling bug hit last month (I think it was 18.2.1?), NoSQL API got patched in like 2 days while MongoDB API users waited weeks.

MongoDB API: Good for migrations when you can't afford to rewrite everything.

Existing Mongo

DB drivers work, which is nice. But here's the fun part

• it's not actually MongoDB. GridFS doesn't work, some aggregation pipeline operations behave differently, and good luck debugging why your compound indexes aren't being used properly. I spent three days figuring out why our session store was consuming 10x more RUs than expected.

Table API: The boring one that actually works reliably.

Key-value operations only, but they're fast and cheap. Perfect for user sessions, feature flags, or anything that doesn't need complex queries. I've never had a production incident with Table API because there's not much to break.

Cassandra API: Time-series data and nothing else.

CQL works until you try using secondary indexes

• then you discover half the features are missing or behave weirdly. One team I worked with spent two weeks debugging why their WHERE clauses weren't working, turns out Cosmos DB's Cassandra doesn't support filtering on non-primary key columns the same way.

Gremlin API: Graph databases for when you hate yourself and everyone around you.

Query syntax looks like someone threw Cypher and SQL into a blender. Performance? Good fucking luck

• I've seen a simple "find friends of friends" query somehow eat 2,000 RUs while an identical traversal cost 50 RUs. Still have no idea why. Only use this if you absolutely need graph operations and enjoy explaining to your manager why the database budget tripled.

The Reality Behind "Multi-API Magic"

Cosmos DB stores everything in their proprietary ARS format and translates to whatever API you're using. Clever engineering, but here's what bites you:

• **No

SQL gets the best performance**

• other APIs have translation overhead
• Some features are NoSQL-only
• stored procedures, triggers, patch operations
• MongoDB compatibility isn't 100%
• aggregation pipelines can consume 2x the RUs
• Mixing APIs is asking for trouble
• don't even think about it

When Each API Makes Sense (Real Talk)

Use NoSQL API:

• You're starting fresh
• You want new features first (vector search, full-text search)
• You need stored procedures or server-side logic
• You want the most efficient RU consumption

Use MongoDB API:

• You're migrating existing MongoDB code
• Your team refuses to learn new syntax
• You have complex aggregation pipelines that work
• You're stuck with existing MongoDB tooling

Use Table API:

• Simple key-value lookups only
• You're migrating from Azure Table Storage
• You want predictable, cheap operations
• Complex queries aren't needed

Use Cassandra API:

• Time-series or IoT data at massive scale
• You're already using Cassandra and it works
• You need wide-column data modeling
• You understand CQL limitations in Cosmos DB

Use Gremlin API:

• You absolutely need graph traversals
• Building recommendation engines
• Fraud detection with relationship analysis
• You enjoy debugging nightmare query performance

The Brutal Truth About RU Consumption

Every API uses Request Units, but the costs vary wildly:

• Point reads: 1 RU per 1KB (only thing that's consistent)
• Writes: 5-8 RUs per 1KB depending on API overhead
• Queries:

No

SQL is cheapest, MongoDB costs 20-30% more, Gremlin will bankrupt you

• Cross-partition queries: All APIs get destroyed equally

I watched one team's Mongo

DB aggregation pipeline absolutely destroy their budget

• 800 RUs for a query that would cost maybe 20 RUs in NoSQL.

Turns out they had these pointless $unwind operations that Cosmos DB just couldn't figure out how to optimize. Took them three weeks to unfuck it, but their monthly bill dropped from like $4,000 to $1,200.

Real Decision Framework

Use NoSQL API unless you have a damn good reason not to. It gets new features first, best tooling, and burns the fewest RUs.

Only use other APIs if:

1. You're migrating existing code and can't afford a full rewrite
2. Your team will quit if they have to learn new syntax
3. You need specific features (graph traversals, Cassandra wide columns)

Don't get clever with multiple APIs. Pick one, stick with it, and resist the urge to use them all just because Microsoft lets you.

You've picked your API (hopefully NoSQL) and now you need to set it up. Here's the setup guide with all the ways you'll fuck this up and how to fix it.

The decisions you make in the next 30 minutes determine whether you spend $500/month or $5,000/month on the same workload. No pressure.

Creating Your Account (First Way You'll Mess Up)

The Azure Portal Trap
Don't click through the portal defaults like an idiot. Teams blow their entire budgets because they trust Microsoft's "helpful" default settings. Use the quickstart but ignore literally every default value they suggest.

Critical decisions that'll destroy your budget:

• API Selection: Pick wrong, rebuild everything later
• Location: Choose based on where users are, not where you work
• Capacity Mode: Provisioned vs Serverless - wrong choice means overpaying or throttling
• Backup Policy: Continuous backup costs extra but saves your job

Provisioned vs Serverless Reality:

• Provisioned: Pay even when nobody uses your app, cheaper with consistent traffic
• Serverless: Costs 2x per operation, no minimum charge - fine for dev, death for production

A team I worked with picked Serverless for production because "it scales automatically." Their first traffic spike cost $3,000 in a single day. Serverless charges per RU consumed, not provisioned capacity.

Partition Keys: Where Dreams Go to Die

This is where most people destroy their Cosmos DB setup. Get the partition key wrong and you're rebuilding everything from scratch.

Partition key rules that'll save your job:

• Pick something with thousands of unique values (not 5)
• Make sure queries don't scan every partition
• You can NEVER change it after creating the container
• Avoid hot spots like timestamps or status fields

Real examples of how teams destroyed their apps:

E-commerce Epic Fail:

// What they did (complete disaster):
"partitionKey": "/orderStatus"
// Result: 90% of orders in "pending" partition, constant 429 errors

// What actually works:
"partitionKey": "/customerId"
// Result: Even distribution, fast queries

IoT Catastrophe:

// The obvious stupid choice:
"partitionKey": "/timestamp"
// Result: All current data destroys one partition

// Less obvious but equally stupid:
"partitionKey": "/deviceType"
// Result: Tesla Model 3 devices overwhelm everything

// What works:
"partitionKey": "/deviceId"
// Result: Even distribution

Multi-tenant Disaster:

// Lazy choice that killed performance:
"partitionKey": "/tenantPlan"
// Result: All enterprise customers in one partition

// The fix:
"partitionKey": "/tenantId"
// Result: Perfect isolation

I watched one team spend 6 weeks rebuilding their entire fucking data model because some genius decided to partition on orderStatus. Guess what? 95% of orders are "pending" so that one partition was getting absolutely hammered. Queries took 30+ seconds and users were ready to throw their laptops out the window.

Consistency Levels: Choose Your Own Adventure

Cosmos DB has five consistency levels. Pick wrong and you'll either blow your budget or ship data bugs.

Session Consistency (Default): Just use this

• Users see their own writes immediately
• Might not see other users' writes right away
• Works for 90% of applications
• Costs 1x RUs (baseline)
• Gotcha: Multi-device users see inconsistencies

Strong Consistency: When money's involved

• Everyone sees identical data always
• Banking, payments, inventory where wrong data = lawsuit
• Costs 2x RUs (ouch)
• Single write region only (kills global performance)

Eventual Consistency: When you don't care

• Data becomes consistent eventually, maybe in seconds
• Perfect for analytics, logging, "close enough" scenarios
• Cheapest at 1x RUs
• Users see stale data for random amounts of time

Bounded Staleness: The compromise nobody wants

• Data might be X seconds old or Y versions behind
• Collaborative editing, leaderboards
• Costs 2x RUs without strong guarantees
• Most teams should just use Session instead

Consistent Prefix: The weird one

• See writes in order but might miss recent ones
• Social feeds, activity streams
• Costs 1x RUs
• Rarely needed in practice

95% of teams should use Session consistency. Don't overthink it unless you're handling money or have bizarre requirements.

The Index Trap That'll Kill Your Performance

Cosmos DB indexes everything by default. Every property in your JSON gets indexed, which sounds great until you realize you're paying to index 50MB blob fields you never search.

How to not destroy your RU budget:

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {
      "path": "/userId/?" // Only index what you query
    },
    {
      "path": "/createdDate/?" // Timestamp for sorting
    }
  ],
  "excludedPaths": [
    {
      "path": "/largeDescription/*", // Don't index big text
      "path": "/binaryData/*", // Never index blobs
      {
      "path": "/*" // Exclude everything else
    }
  ]
}

Indexing strategies:

• Default: Index everything (expensive writes, fast queries)
• Smart: Only index queried fields (cheap writes, fast targeted queries)
• Dumb: No indexes (cheap writes, everything else is slow)

A team I worked with indexed their document store including 5MB PDF contents. Every write consumed 100+ RUs because Cosmos DB was indexing binary data. Took them three months and $20k before they figured out why their bill was insane.

RU Capacity: How to Not Go Broke

Microsoft's capacity calculator will lie to you. It gives optimistic estimates that never match production reality. Whatever number it spits out, multiply by 2x for a realistic starting point.

Request Units are how Cosmos DB charges you. Estimate wrong and you'll either get throttled or pay 10x more than expected.

RU math that matters:

• Read 1KB: 1 RU
• Write 1KB: 5-8 RUs
• Delete: 5-8 RUs
• Query scanning 100 docs: 50-200 RUs (wildly depends on complexity)

Provisioned capacity reality:

• Too low: 429 throttling errors during traffic spikes
• Too high: Pay for capacity you never use
• Autoscale: Scales 10%-100% of max, costs 1.5x at minimum

Start with manual provisioning at 25% of what you think you need. Monitor for a week. Increase based on actual usage, not Microsoft's fairy tale projections.

Global Distribution: Great Feature, Expensive Reality

Global distribution sounds awesome until you see the bill. Here's what matters for multi-region deployments:

Start simple:

1. One write region where most users are
2. Add read regions for global users
3. Don't enable multi-region writes unless you absolutely need it

Multi-region cost breakdown:

• Single region: $1,000/month
• Multi-region reads: $1,500/month (+50%)
• Multi-region writes: $3,000/month (+200%)

Code that works:

var options = new CosmosClientOptions()
{
    ApplicationName = "MyApp",
    ApplicationRegion = Regions.WestUS2, // Primary region
    ConnectionMode = ConnectionMode.Direct // Always Direct
};

The Emulator: Your New Best Friend

Use the Cosmos DB emulator for development or spend $200/month testing things.

## Docker setup that works
docker run -p 8081:8081 -m 3g --name cosmos-emulator \
  microsoft/azure-cosmosdb-emulator

Emulator gotchas:

• Self-signed SSL certificates (ignore in dev)
• Performance doesn't match production
• New features lag behind
• Breaks randomly on Windows updates

Monitoring That Matters

Your RU consumption graph becomes your obsession. Normalized RU utilization shows which partition keys eat your budget. One partition consistently above 80% = bottleneck.

Set up alerts or get bill surprises:

{
  "alertName": "RU Consumption > 80%",
  "threshold": 80,
  "action": "Wake someone up"
}

Essential metrics:

• RU consumption: > 80% = add capacity now
• 429 errors: Throttling = users getting timeouts
• P99 latency: > 100ms = something's broken
• Monthly cost: Track weekly, not monthly

Production checklist:

• Partition key tested with realistic data
• RU consumption measured under load
• 429 error handling with retry patterns
• Backup policy configured
• Cost alerts set up
• Team knows how to debug at 3 AM

That's it. Everything else is optimization for later. Get these basics right and you won't hate Cosmos DB.