Azure Cosmos DB: AI-Optimized Implementation Guide

Configuration

API Selection Decision Matrix

Primary Recommendation: NoSQL API (Core SQL)

• Performance: Best RU efficiency, gets features first
• Feature Support: Stored procedures, triggers, patch operations
• Update Priority: Patches released 2+ days faster than other APIs
• RU Consumption: 20-30% more efficient than MongoDB API

Alternative APIs - Use Cases Only

API	Use When	Avoid When	RU Cost Multiplier
MongoDB	Migrating existing MongoDB code	Starting fresh	1.2-1.3x
Table	Simple key-value operations only	Complex queries needed	1.0x
Cassandra	Time-series/IoT at massive scale	Need secondary indexes	1.1x
Gremlin	Graph traversals required	Performance matters	2-10x

Production-Ready Configuration Settings

Account Setup - Critical Decisions

{
  "capacityMode": "Provisioned", // Serverless costs 2x per operation
  "consistencyLevel": "Session", // 95% of applications
  "backupPolicy": "Continuous", // Saves jobs during disasters
  "multiRegionWrites": false // +200% cost, rarely needed
}

Partition Key Design Rules

• Minimum unique values: 1000+ (not 5-10)
• Avoid: timestamps, status fields, device types
• Prefer: userIds, customerIds, deviceIds
• Cannot change: After container creation - rebuild required

Proven Partition Key Patterns

// E-commerce: Customer isolation
"partitionKey": "/customerId"

// IoT: Device distribution
"partitionKey": "/deviceId"

// Multi-tenant: Tenant isolation
"partitionKey": "/tenantId"

// Content: User-based access
"partitionKey": "/userId"

Indexing Policy - Production Optimized

{
  "indexingMode": "consistent",
  "automatic": true,
  "includedPaths": [
    {"path": "/userId/?"},
    {"path": "/createdDate/?"}
  ],
  "excludedPaths": [
    {"path": "/largeDescription/*"},
    {"path": "/binaryData/*"},
    {"path": "/*"}
  ]
}

Resource Requirements

Cost Structure Reality

Monthly Costs by Scale

• Small app (10K users): $300-1,200/month
• Medium app (100K users): $1,500-5,000/month
• Large app (1M+ users): $5,000-25,000/month

RU Capacity Estimation

• Microsoft calculator accuracy: Multiply by 2x for realistic estimates
• Starting point: 25% of estimated need, monitor for 1 week
• Autoscale costs: 1.5x minimum rate, scales 10%-100% of max

Operation Costs in Request Units

Operation	Document Size	RU Cost	Performance Impact
Point read by ID	1KB	1 RU	Only consistent cost
Write new document	1KB	5-6 RUs	Higher with many indexes
Update existing	1KB	6-8 RUs	Depends on changed fields
Simple query	10 results	5-15 RUs	Add partition key or pay more
Cross-partition scan	100 results	100-500 RUs	Destroys budget during spikes
Complex aggregation	1000 docs	200-1000 RUs	Can bankrupt applications

Time Investment Requirements

Setup and Implementation

• Basic setup: 1-2 days with proper guidance
• Partition key mistakes: 6+ weeks rebuild time
• Learning curve by API: NoSQL (2-3 weeks), MongoDB (easy if known), Cassandra (1-2 months), Gremlin (3-6 months)

Migration Timelines

• From MongoDB: Weeks with Database Migration Service
• From SQL Server: Months (requires denormalization)
• Downtime planning: Migration tools overstate "zero downtime" capabilities

Critical Warnings

Breaking Points and Failure Modes

Partition Key Disasters

• Hot partition threshold: >80% normalized RU utilization
• Common failures:
  • E-commerce using /orderStatus (95% orders are "pending")
  • IoT using /timestamp (all current data in one partition)
  • Multi-tenant using /tenantPlan (enterprise customers overwhelm partition)

Query Performance Killers

• Cross-partition queries: Missing partition key in WHERE clause
• Index explosion: Indexing 5MB+ binary fields consumes 100+ RUs per write
• Aggregation pipeline inefficiency: MongoDB operations can cost 800 RUs vs 20 RUs in NoSQL

Cost Explosion Triggers

1. Multi-region writes enabled: +200% cost increase
2. Default indexing on large fields: Binary data indexing
3. Autoscale stuck at maximum: Poor partition key distribution
4. Serverless in production: 2x cost per operation under load

Consistency Level Gotchas

Session Consistency (Recommended)

• Multi-device users: See inconsistencies across devices
• Cost: 1x RUs (baseline)
• Appropriate for: 95% of applications

Strong Consistency Limitations

• Regional restriction: Single write region only
• Cost: 2x RUs
• Required for: Financial transactions, payments, inventory

Performance Troubleshooting

429 Throttling Errors

• Root cause: Hot partitions or insufficient RUs
• Immediate fix: Increase provisioned capacity
• Long-term fix: Redesign partition key
• Code requirement: Implement retry logic with exponential backoff

Query Performance Issues

• 30+ second queries: Usually partition key problems
• Debug method: Check partition distribution with COUNT GROUP BY
• Quick fixes: Add partition key to WHERE, avoid SELECT *, increase RUs temporarily

Integration Limitations

MongoDB API Compatibility

• Missing features: GridFS, some aggregation pipeline operations
• Behavioral differences: Compound indexes not used properly
• Performance gap: 20-30% higher RU consumption than NoSQL API

Multi-API Usage

• Technical possibility: Same data accessible via different APIs
• Reality: Data corruption, performance issues, debugging nightmares
• Best practice: One API per container, never mix

Backup and Recovery

Backup Policy Critical Settings

• Continuous backup: Required for point-in-time recovery
• Cost impact: Additional charges but saves jobs during disasters
• Recovery reality: Point-in-time restore can take hours

Monitoring Requirements

Essential Alerts

• RU consumption >80%: Immediate capacity increase needed
• 429 error rate >1%: User experience degradation
• P99 latency >100ms: Performance investigation required
• Monthly cost variance >20%: Configuration review needed

Metric Interpretation

• Normalized RU utilization: Per-partition health indicator
• Hot partition detection: One partition consistently >80% utilization
• Cross-partition query identification: High RU consumption without partition key

Operational Realities

Development vs Production

• Emulator limitations: Performance doesn't match production, SSL certificate issues
• Development costs: $200+/month without emulator usage
• Testing requirements: Load testing with realistic data volumes mandatory

Team Knowledge Requirements

• Partition key design: Cannot be learned from documentation alone
• RU optimization: Requires understanding of indexing and query patterns
• Troubleshooting skills: 3 AM debugging scenarios require deep Cosmos DB knowledge

Hidden Dependencies

• SDK connection management: Tricky with .NET SDK v3
• Change feed processing: Requires understanding of continuation tokens
• Bulk operations: Essential for high-throughput scenarios

This guide prioritizes operational intelligence over theoretical knowledge, focusing on real-world implementation challenges and cost optimization strategies based on production experience.