A feature launches with a data model that makes every request scan across partitions. Another team adds a cache but never defines expiry or invalidation, so users see stale values. Both systems can scale their infrastructure; neither can repair an access pattern that was never designed.
What you’ll learn
- Decide when Cosmos DB’s distributed document model fits a workload.
- Choose partition keys based on request patterns and distribution.
- Compare consistency options at a high level.
- Explain cache-aside, expiry, invalidation, and cache failure behavior.
- Inspect Cosmos DB accounts without creating or changing resources.
Where this fits
Module 22, Phase 5, Part 4. Read Relational Databases; next: the private PostgreSQL deployment lab.
Prerequisites
- Basic API, JSON, and database concepts.
- Azure CLI 2.91.0+ and Reader access for the optional exercise.
- No resources are created; cost is none.
Cosmos DB: design around the request
Azure Cosmos DB is a globally distributed database service with multiple APIs. For its NoSQL API, data is organized in databases and containers. Items in a container are distributed into logical partitions by a partition key; physical partitions are managed by the service.
Choose a key that appears in common reads and writes, distributes traffic and storage, and avoids a single hot value. The key affects query routing, transaction scope, throughput, and future data access. A query that omits its partition key may fan out across many partitions. Model a few real API requests and expected item counts before choosing.
Cosmos DB offers consistency levels that trade read freshness against availability and latency. The right choice depends on what the application must observe after a write, not on selecting the strongest label by default. Throughput may be provisioned or autoscaled depending on account and workload configuration; requests consume request units (RUs), and request patterns drive the bill.
Don’t choose Cosmos DB merely because the data is JSON. A relational workload with joins, cross-row transactions, and flexible ad hoc querying may be a better fit for a relational database. Review API-specific feature support, consistency behavior, regional topology, and pricing before committing.
Caching: accelerate reads without changing the source of truth
The cache-aside pattern checks a cache first. On a miss, the application reads the authoritative database, returns the result, and populates the cache with an expiry. Writes update the source of truth and then invalidate or refresh affected cache entries.
Every cached value needs an explicit freshness policy. Time-to-live (TTL) bounds how long an item may stay in cache, but it does not by itself guarantee immediate consistency after a write. Consider stale reads, cache stampedes, hot keys, eviction, cache outage, and deployment/version changes.
Azure Managed Redis is Microsoft’s current managed Redis service offering. Confirm the current service lifecycle, supported tiers, features, migration options, and regional availability in Azure documentation before selecting it or migrating an older cache. A cache is usually disposable derived state: applications must keep operating safely when entries disappear or the cache is temporarily unreachable.
Hands-on: inspect Cosmos DB accounts
RESOURCE_GROUP="<EXISTING_RESOURCE_GROUP>"
az cosmosdb list --resource-group "$RESOURCE_GROUP" \
--query "[].{name:name, location:location, kind:kind, consistency:properties.consistencyPolicy.defaultConsistencyLevel}" \
--output table
The command reads control-plane account metadata; it does not reveal application data or prove that queries are correctly partitioned.
✅ Checkpoint: For one representative operation, write down its partition key, expected RU cost measurement, freshness requirement, and behavior on cache miss or cache outage.
Security, cost, and production choices
Use managed identity and data-plane role-based access where supported, scope permissions to the workload, and restrict network access. Avoid account keys in application code. Keep sensitive data out of cache keys and values unless required and protected. Use TLS and review cache persistence and network configuration according to the data’s classification.
Cosmos DB cost depends on request units, storage, backup, regions, and networking. Cache cost depends on tier/size, replicas, persistence, network, and operations. A cache that stores too much or misses frequently can add cost without reducing database load. Load-test realistic keys, skew, concurrency, and failure modes.
Troubleshooting
- High RU consumption: Inspect query metrics, index policy, cross-partition fan-out, returned payload size, and point-read opportunities.
- One partition is hot: Measure key distribution and per-key traffic; redesign access or partition strategy before peak traffic.
- Unexpected stale data: Check consistency, TTL, invalidation ordering, and application-level caching.
- Cache miss rate is high: Check key construction, TTL, eviction, deployment churn, and whether the workload has reusable reads.
- Database slows when cache fails: Add bounded concurrency, safe fallback, timeouts, and circuit-breaking behavior; avoid retry storms.
- Cache returns another user’s data: Include tenant/user scope in keys and verify authorization independently of cache presence.
- Cost grows unexpectedly: Review RU consumption, autoscale behavior, storage, replication, cache size, and egress.
Five-pillar readiness checklist
- Reliability: Define cache outage behavior, consistency needs, backup, and multi-region failover.
- Security: Use identity-based data access, TLS, network controls, and safe cache key design.
- Cost Optimization: Measure RU demand, cache hit ratio, storage, regions, and data transfer.
- Operational Excellence: Monitor latency, throttling, hot partitions, errors, cache misses, and failover.
- Performance Efficiency: Test representative partition keys and data skew under expected concurrency.
Cleanup
No Azure resources were created. No cleanup is needed.
Key takeaways
- Model Cosmos DB around request patterns and partition-key distribution.
- Stronger consistency has tradeoffs; use only the level the application needs.
- A cache is derived state, not the source of truth.
- TTL bounds age but does not replace write invalidation design.
- Measure realistic workload cost and behavior before scaling.
Next: Connect Your Azure Container App to a Private PostgreSQL Database.
Series navigation: Previous: Relational Databases · Current: Phase 5, Part 4 · Next: Private PostgreSQL Lab