Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 57 ยท Databases and Data

Azure Cosmos DB

Learn Azure Cosmos DB: containers, partition keys, request units, the five consistency levels and the change feed, with runnable stand-ins.

Azure Cosmos DB is Microsoft's globally distributed, fully managed database for applications that need low latency at any scale. Unlike Azure SQL Database, which is a relational engine you size by compute, Cosmos DB stores items (usually JSON documents) in containers, spreads them across servers automatically, and charges you in a currency of its own: request units.

Three ideas decide whether a Cosmos DB design works: the partition key you choose, the request units (RUs) each operation costs, and the consistency level you accept when you read. This lesson explains them, shows read-only SDK code, and gives you Node.js stand-ins that model partitioning, RU accounting, throttling and the change feed. The real service needs an Azure account and a database, so it cannot run on this site; the stand-ins use invented numbers that follow the real shape.

APIs, accounts, databases and containers

You create one Cosmos DB account and pick an API that decides the data model and the wire protocol:

API Data model Use it when
NoSQL JSON documents queried with a SQL-like language You are building something new. It is the native API and gets features first
MongoDB Documents, MongoDB wire protocol You already have an app that talks to MongoDB
Apache Cassandra Wide-column You are moving a Cassandra workload
Apache Gremlin Graph You traverse relationships (people, routes, dependencies)
Table Key/value You are moving from Azure Table storage and want global distribution

The choice is made per account and cannot be changed later. The rest of this lesson uses the NoSQL API terms.

Inside an account the hierarchy is account, database, container, item. A container is the unit of scale: it has a partition key, a throughput setting and an indexing policy. An item is a JSON document, and every item has an id that is unique within its logical partition.

Partition keys

When you create a container you choose a partition key path, such as /customerId. Cosmos DB hashes the partition key value of each item and uses the hash to decide which physical server stores it. All items that share a key value form a logical partition.

This has rules you must design around:

  • A single logical partition can hold at most 20 GB of data, and its throughput is limited to what one physical partition can serve.
  • Operations that name the partition key (a point read or a single-partition query) touch one partition and are cheap.
  • Queries that do not name it are cross-partition (fan-out): the request goes to every partition and costs more.
  • The partition key cannot be changed in place later. Moving to a new key means creating a new container and copying the data.

A good key has many distinct values, spreads reads and writes evenly, and appears in most queries. /customerId is usually good for an orders container. /country is usually bad: a few huge values become hot partitions while the others sit idle. For multi-tenant apps, /tenantId is common, and hierarchical partition keys (up to three levels, for example tenant then user) help when one tenant is very large.

flowchart LR
    A["Client request<br/>partition key = c-102"] --> H["Hash of the key"]
    H --> P1["Physical partition 1<br/>c-102, c-340, ..."]
    H -.-> P2["Physical partition 2"]
    H -.-> P3["Physical partition 3"]

A request that names the partition key goes straight to one partition. Without the key, the query has to ask all of them.

Request units

Cosmos DB hides CPU, memory and IOPS behind one measure, the request unit (RU). By definition, reading a 1 KB item by its id and partition key (a point read) costs 1 RU. Everything else is priced relative to that: writes cost several times more than reads, larger items cost more, and a query costs according to the work of finding and returning its results (index lookups, items scanned, results returned). Every response tells you its charge in a header, so you can measure rather than guess.

You buy RUs per second in one of three ways:

  • Provisioned throughput (manual): a fixed RU/s you set. Predictable, billed hourly whether used or not.
  • Provisioned throughput (autoscale): you set a maximum, and the container scales between 10% of it and the maximum depending on load.
  • Serverless: no provisioning; you pay for the RUs your requests consume and for storage. It suits small, spiky or development workloads, with limits on size and throughput per container.

If requests arrive faster than the RU/s you provisioned, the service answers HTTP 429 (Too Many Requests) with a retry-after hint. The SDKs retry automatically a few times, which hides small bursts; sustained overload means you must raise throughput, fix a hot partition, or make the queries cheaper.

Reading and writing with the SDK

The following Node.js code is read-only here: it needs an account, the @azure/cosmos and @azure/identity packages, and a role assignment. It uses a managed identity instead of an account key, as in Managed Identities and Service Principals.

JavaScript
import { CosmosClient } from "@azure/cosmos";
import { DefaultAzureCredential } from "@azure/identity";

const client = new CosmosClient({
  endpoint: "https://my-account.documents.azure.com:443/",
  aadCredentials: new DefaultAzureCredential(),
});

const container = client.database("shop").container("orders");

// Write: the partition key value comes from the item's /customerId.
const { resource, requestCharge } = await container.items.create({
  id: "order-9001",
  customerId: "c-102",
  total: 49.5,
});
console.log("write cost:", requestCharge, "RU");

// Point read: id + partition key value. The cheapest operation.
const read = await container.item("order-9001", "c-102").read();

// Single-partition query: the key is pinned, so one partition answers.
const { resources } = await container.items
  .query(
    {
      query: "SELECT * FROM c WHERE c.customerId = @id AND c.total > @min",
      parameters: [
        { name: "@id", value: "c-102" },
        { name: "@min", value: 20 },
      ],
    },
    { partitionKey: "c-102" }
  )
  .fetchAll();

Two details are worth noticing. The query is parameterized, which avoids injection and lets the service reuse plans. And the partitionKey option is passed explicitly, so the SDK does not need to fan out.

A partitioned store with RU accounting: a stand-in

The stand-in below is not Cosmos DB. It is a tiny in-memory store that hashes a partition key to one of three partitions and charges RUs by a simple invented rule: a point read costs 1 RU per KB, a write costs 5 RU per KB, and a query costs 1 RU per partition it has to visit plus 0.5 RU per item it returns. Real charges depend on indexing and item shape; use the real response header for real numbers. What carries over is the pattern: point reads and single-partition queries are far cheaper than fan-out.

Node.js Partitions and request charges

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice that the cross-partition query costs more because it visits every partition, even when the answer is the same kind of data. In real Cosmos DB the gap grows with the number of physical partitions, which is why queries should include the partition key whenever the application knows it.

Throttling: a stand-in

The next stand-in models the budget. It provisions 100 RU/s, spends it on requests inside one second, and returns an error with a retry-after hint when the budget runs out. A client that waits and retries succeeds in the next second, which is what the SDKs do for short bursts.

Node.js Run out of RU/s and retry

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Real throttling is per physical partition: a container with 10,000 RU/s over ten partitions gives each about 1,000 RU/s, so one hot partition can return 429 while the container as a whole looks idle. That is the strongest argument for a well-spread partition key.

Consistency levels

A globally distributed database must trade freshness against latency and availability. Cosmos DB lets you choose among five consistency levels, from strongest to weakest:

  1. Strong: reads always see the latest committed write (linearizable). The cost is higher write latency, and the account cannot span regions that are too far apart.
  2. Bounded staleness: reads may lag writes, but by at most K versions or T time. Ordered and predictable.
  3. Session (the default): within one client session you read your own writes and see monotonic reads. Other clients may lag a little. This is right for most applications.
  4. Consistent prefix: reads never see writes out of order, but may be behind.
  5. Eventual: the cheapest and fastest; replicas converge eventually and ordering is not guaranteed.

You set a default on the account and can relax it per request, but not strengthen it beyond the account default. Weaker levels cost fewer RUs and answer faster. A shopping cart usually wants session; a leaderboard might accept eventual; a ledger that must never show a stale balance may need strong.

The change feed

Every container has a change feed: an ordered log of items that were created or updated, readable by other programs. (In the default latest-version mode it shows the final state of each change, not deletes; use a soft-delete flag, or the all-versions-and-deletes mode where available, if you need deletions.) Ordering is guaranteed within a logical partition, not across partitions.

Typical uses are keeping a search index or cache in sync, triggering an Azure Function when an order is created (see Azure Functions), building materialized views and streaming changes to analytics. A consumer remembers a continuation token (or lease) so it resumes where it stopped.

Node.js Read the change feed with a checkpoint

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The first read returns the latest version of each item (order-1=paid), not the intermediate new state. This mirrors how the latest-version change feed behaves. The checkpoint is what makes the consumer restartable.

Common mistakes

  • Choosing a low-cardinality or skewed key such as a status or country. Choose something with many values that your queries filter on.
  • Treating Cosmos DB as a relational database. Cross-container joins do not exist; model data so common reads touch one item or one partition, embedding related data when it is read together and changes together.
  • Using SELECT * fan-out queries on hot paths. Pass the partition key, project only the fields you need, and look at the request charge.
  • Over-provisioning "to be safe" with manual throughput. Autoscale or serverless often costs less for uneven load (see Pricing, Cost Management and Budgets).
  • Using account keys in code. Prefer Entra authentication and role assignments.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does it cost, by definition, to read a 1 KB item by id and partition key?

    A 1 KB point read is the reference unit: 1 RU. Writes and queries are priced relative to it.
  2. 2. Which partition key is most likely to cause a hot partition in an orders container?

    A low-cardinality or skewed key sends most traffic to one logical partition, which is limited to one physical partition's throughput.
  3. 3. Your app receives HTTP 429 from Cosmos DB during a long traffic spike. What does that mean?

    429 is the throttling response. SDK retries hide short bursts; sustained 429s mean more throughput, better key distribution or cheaper queries.
  4. 4. Which consistency level is the default and guarantees a client reads its own writes?

    Session consistency gives read-your-writes and monotonic reads within a session at lower cost than strong, which is why it is the default.
  5. 5. What is the change feed used for?

    The change feed lets consumers react to inserts and updates, resuming from a continuation token or lease.

Summary

  • A Cosmos DB account uses one API (NoSQL for new work); data lives in containers of JSON items.
  • The partition key decides data placement and cost: choose many distinct values, even spread and presence in most queries. It cannot be changed in place.
  • Request units price every operation; a 1 KB point read is 1 RU, and queries that fan out cost more. Exceeding RU/s returns 429.
  • Throughput is provisioned (manual or autoscale) or serverless.
  • Five consistency levels trade freshness for latency; session is the default.
  • The change feed is an ordered, resumable log of changes within each logical partition.

Next: PostgreSQL, MySQL and Redis on Azure.