CH06-03: Document Data with Azure Cosmos DB

Goal

The previous section explained why relational structure is useful when relationships, constraints, and transactions are central. This section looks at a different shape: document-oriented and selected non-relational data where the application often reads and writes an aggregate together.

Azure Cosmos DB can be powerful, especially for globally distributed, low-latency, high-scale workloads. It should also be chosen with care.

The durable idea is:

Cosmos DB is a strong choice when the data model, access pattern, partitioning strategy, and scale requirements fit it.

The Short Version

Azure Cosmos DB is a fully managed NoSQL database service with global distribution capabilities. It supports multiple APIs and data models, but this section focuses mostly on the common document-style pattern: storing application data as JSON-like documents that are read and written by key or by known query paths.

Cosmos DB is often a strong fit when the workload needs:

• Flexible document-shaped records.

• Low-latency reads and writes.

• High throughput with a clear partitioning model.

• Global distribution or multi-region access.

• Tunable consistency choices.

• A request-unit-based capacity and cost model that the team can actively manage.

The design question is not whether NoSQL is modern. The design question is whether the workload has access patterns that Cosmos DB can serve efficiently and economically.

Document Data as Aggregates

A document often represents an aggregate: a set of related fields the application usually reads and writes together.

For example, a product catalog item might contain:

Product document
    productId
    title
    description
    category
    attributes
    price display data
    regional availability hints
    search metadata

If the application normally retrieves the whole product document by product ID, updates product attributes together, and tolerates schema evolution across product types, a document model may fit well.

That is different from a highly relational order system where many entities need strong transaction rules across tables. A document model can simplify some aggregate reads, but it can make broad joins and ad hoc relational queries harder.

Access Pattern First

Cosmos DB design starts with access patterns.

Product catalog API
    |
    +-- Read product document by productId
    +-- Query products by tenantId and category
    +-- Update product attributes as one aggregate
    +-- Replicate catalog close to regional users, if needed

Before choosing Cosmos DB, ask:

• What are the most common reads?

• What are the most common writes?

• Which fields are used to find data?

• Which queries must be fast and predictable?

• Which queries can be served by a search index, analytics platform, or derived view instead?

• How large can each document become?

• Which data must be updated together?

If these questions are vague, the Cosmos DB design is not ready. Cosmos DB rewards clear access patterns and punishes vague data modeling.

Partition Keys Matter

Partitioning is how Cosmos DB spreads data and throughput. A partition key is the property used to distribute and locate items. In practical terms, it shapes scalability, performance, and cost.

A good partition key usually:

• Has many possible values.

• Distributes reads and writes evenly.

• Appears in common queries.

• Does not change after the item is created.

• Avoids concentrating traffic into a few hot partitions.

For example, a multitenant catalog might consider tenantId, productId, or a hierarchical or synthetic key depending on the query pattern. There is no magic universal key. The right key comes from how the application reads and writes data.

Poor partition-key choices create real pain. A low-cardinality key, such as status, may concentrate traffic. A random key may distribute writes but make common queries expensive if the application rarely filters by that key. A key that later needs to change can require data movement because partition key values are not updated in place.

Consistency Is Application Behavior

Cosmos DB offers multiple consistency levels, from stronger consistency to more availability-oriented and latency-friendly options. You do not need to memorize every level for this chapter. The architectural point is that consistency is user-visible behavior.

Ask:

• After a user updates data, must that same user immediately read the update?

• Can another region show slightly older data for a short time?

• Is ordering important?

• Is the workload read-heavy, write-heavy, or globally distributed?

• What latency and availability trade-offs are acceptable?

Consistency is not just a database checkbox. It changes how users experience the system and how developers reason about application state.

Global Distribution Is Not a Free Fix

Cosmos DB can distribute data across regions, which is valuable for global applications that need low-latency access near users or resilience across regions.

But global distribution does not fix poor modeling. If the partition key is weak, queries are unclear, documents grow without control, or the application expects relational joins everywhere, adding regions may make the system more expensive and harder to reason about.

Use global distribution when the business requirement is real:

• Users in several geographies need low-latency operational reads.

• The application is designed for the selected consistency behavior.

• The data model and partitioning strategy can scale cleanly.

• The team understands the cost of throughput, storage, indexing, and replication.

Cost Follows Requests, Indexing, and Shape

Cosmos DB cost and performance are closely tied to request units, often called RUs. A request unit is a normalized measure of the work needed to perform database operations. Reads, writes, queries, indexing, document size, and consistency choices all influence RU consumption.

The practical lesson is simple:

Cosmos DB cost should be discussed while modeling the data, not after production traffic arrives.

Teams should test representative queries, monitor RU consumption, review indexing policy, and understand whether provisioned throughput, autoscale, or serverless options match the workload pattern.

Example: Product Catalog and Session State

In the commerce platform, Cosmos DB might fit two possible areas.

The product catalog may fit if product records are read as documents, product attributes vary by category, and regional low-latency access matters.

User session state may fit if the system needs fast key-based access to durable session documents. If the session state is temporary and can be rebuilt, a cache might also be part of the answer. The important move is to classify the data responsibility before naming the service.

Cosmos DB may be part of the design. It should not become the answer for every data problem.

Common Mistakes

• Choosing Cosmos DB before defining the partition key.

• Modeling highly relational data as documents without understanding query consequences.

• Ignoring request-unit cost, document size, indexing, and query patterns.

• Assuming global distribution automatically fixes poor data modeling.

• Treating consistency as a default setting instead of an application behavior decision.

• Using Cosmos DB for large binary files that belong in object storage.

If Someone Asks You

When should you choose Cosmos DB?

A good answer is:

I choose Cosmos DB when the workload has a document or non-relational access pattern that fits its partitioning and scale model. I define the main reads and writes, choose a partition key that distributes traffic and matches queries, decide the consistency behavior, and test RU cost early. Cosmos DB is excellent for clear high-scale and globally distributed patterns, but it is not a shortcut around data modeling.

What You Should Remember

Cosmos DB rewards clear access patterns and punishes vague data modeling.

Questions to Check Understanding

1. Why is the partition key central to Cosmos DB design?

2. When might document data be a good fit?

3. Why should cost be discussed early with Cosmos DB?