Skip to main content

Hot Partitioning in Azure Cosmos DB

00:07:36:30

(The mechanism under the bonnet)

What is Azure Cosmos DB?

Azure Cosmos DB is a database service in the cloud that helps applications store and access data swiftly, reliably, and from any corner of the globe. Think of it as a super-flexible, super-fast and robust storage system for your app's information.

Key Features of Azure Cosmos DB

  1. Global Access

    • Your data can be copied to different parts of the world automatically.
    • Example: Someone in New York and someone in Tokyo can both access your app quickly because the data is close to them.

  2. Supports Different Types of Data

    • You can store data in formats like:
    • JSON (documents)
    • Tables (key-value pairs)
    • Graphs (connections between items, like social networks)
    • Columns (like in Cassandra)

  3. Scales Automatically

    • If lots of people start using your app, Cosmos DB can handle the extra load without crashing.

  4. Super Fast

    • Reads and writes happen in just a few milliseconds.

  5. Different Consistency Options

    • You can choose how strict the database is about making sure everyone sees the same data at the same time. Options range from very strict to more relaxed.

  6. Fully Managed

    • Microsoft takes care of updates, backups, and hardware. You just focus on your app.

AWS Equivalent

On Amazon Web Services, a similar service is called Amazon DynamoDB. It also provides fast, globally distributed, fully managed database functionality.

But have you ever wondered why your Cosmos DB container struggles under certain loads?

What is Partition Key in Cosmos DB?

In Azure Cosmos DB, a Partition Key is a way to organize your data so that it can be stored and accessed efficiently, especially when your database grows very large.

Why It Matters

  1. Speeds up queries: Cosmos DB knows where to find data because it's grouped by the partition key.
  2. Helps the database grow: Large amounts of data are split into smaller groups (partitions), so the system doesn't get overloaded.
  3. Avoids bottlenecks: If all data were in one group, some queries could be slow.

Let's say you're building a system to store book borrowing records from a multi-branch library system in the United Kingdom like Libraries Connected or LibrariesWest. You choose Azure Cosmos DB, and you decide to use the book genre as your partition key (e.g., "Sci-Fi", "Science", "Literature", and so on).

Suddenly, during a certain time of year, borrowing spikes for the "Sci-Fi" genre, and your Cosmos DB container starts to throttle or lag.

What Really Happens Under the Bonnet in Cosmos DB

1. Insert Request

You insert an item like:

json
{ "id": "1", "genre": "Sci-Fi" }

2. Hashing the Partition Key

Cosmos DB hashes the value "Sci-Fi" (because you chose it as Partition Key), let's say it becomes a number like 234582937.

But what is a hash function?

A hash function is like a special machine that takes any input, like text, numbers, or files, and turns it into a fixed-length string of characters, called a hash. Think of it as a digital fingerprint:

  • Each unique input produces a unique hash.
  • Even a tiny change in the input produces a completely different hash.
  • You cannot reverse it to get the original input easily — it's one-way.

Example in simple terms:

  • Input: "Hello" → Hash: "aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d"
  • Input: "hello" → Hash: "5d41402abc4b2a76b9719d911017c592"

Even changing the capital H to a lowercase h changes the hash completely.

You may review a comprehensive list of various hash functions at: List of hash functions.

3. Mapping to a Logical Partition

The ranges created by the hash function are divided into different blocks called partitions. For example, we might have three logical partitions:

  • LP1: keeps hashes that range from 0 to 1,000,000,000
  • LP2: keeps hashes that range from 1,000,000,000 to 2,000,000,000
  • LP3: keeps hashes that range from 2,000,000,000 to 3,000,000,000

The Cosmos DB partitioning system decides which logical partition the hash value maps to. So this hash falls into a specific logical partition (e.g., LP1: Logical Partition 1, which handles a range of hash values).

4. Assigning Logical Partitions to Physical Partitions

In Azure Cosmos DB, physical partitions are the actual storage units (servers) that hold your data and provide throughput (RUs). However, Cosmos DB does not store each logical partition on a separate physical partition. Instead, it uses a mapping system to decide which physical partition will store each logical partition.

Routing/Mapping System: Cosmos DB has an internal routing service that uses the hash value to decide which physical partition will store that logical partition. It acts like a post office: it reads the address (hash) and directs the data to the correct server (physical partition).

Multiple Logical Partitions per Physical Partition:

  • Each physical partition can hold many logical partitions.
  • This allows Cosmos DB to use server resources efficiently.
  • However, if one logical partition receives most of the traffic, it can overload the physical partition, creating a hot partition.

Further details:

5. Problem: All "Sci-Fi" Data Hits the Same Physical Partition

Because "Sci-Fi" generates the same hash, which falls into LP1's hash range, and LP1 is stored in only one physical partition, all the load goes there.

Result: Hot Partition

That physical partition gets overloaded (e.g., exceeding the 10,000 RU/s or 50GB limit), because in Azure Cosmos DB each physical partition has limits:

  • 50 GB of data per partition
  • 10,000 RU/s of throughput per partition

Meanwhile, other physical partitions may remain underutilized. This is called a Hot Partition, and it limits the scalability of your app.

Solution: Use Synthetic Partition Keys

When you pick a partition key, the goal is to spread your data and traffic evenly across all physical partitions in Cosmos DB. If too many items share the same key (like "Sci-Fi"), all that traffic ends up in one logical partition, which may overload a physical partition, creating a hot partition.

A synthetic partition key combines multiple pieces of information into one key. This way, even if many items share the same genre, they can still go to different logical partitions.

How It Works

1. Original Key Example

  • Partition key = "genre"
  • Problem: All "Sci-Fi" items go to one logical partition, which can overload a single physical partition.

2. Synthetic Key Example

  • Partition key = "genre:region" → "Sci-Fi:UK", "Sci-Fi:USA"
    • The hash function sees "Sci-Fi:UK" and "Sci-Fi:USA" as different values, so they go to different logical partitions.
  • Partition key = "genre:date" → "Sci-Fi:2025-05-18"
    • Each date gets its own logical partition, spreading traffic.
  • Partition key = "genre:userId" → "Sci-Fi:User123"
    • Each user has their own partition, avoiding hot spots.

Why This Helps

  • Each different hash maps to a different logical partition.
  • Logical partitions are then distributed across different physical partitions.
  • This allows Cosmos DB to scale horizontally, handling more data and traffic efficiently.
  • No single server gets overloaded, improving performance and avoiding throttling.

Think of it like a supermarket checkout:

  • Original key: Everyone with "Sci-Fi" books goes to the same checkout lane → chaos.
  • Synthetic key: Split by region, date, or user → multiple lanes open, traffic spreads evenly → faster service.

More information:

Other Microsoft-Recommended Partitioning Strategies

High-Cardinality Keys

  • What it is: A high-cardinality key has lots of unique values.
  • Examples: bookId, userId, orderId.
  • Why it helps: If every value is unique, Cosmos DB spreads the data evenly across logical and physical partitions.
  • Simple analogy: Think of it as giving each person a separate checkout lane in a supermarket — no single lane gets overcrowded.

Time-Based Partitioning

  • What it is: Add a timestamp or date to your partition key.
  • Example: "genre:2025-05-18"
  • Why it helps: Data is automatically spread over time, which is ideal for logs, metrics, or time-series data that grows every day.
  • Analogy: Like opening a new lane for each day in a supermarket, so today's shoppers don't clog yesterday's lane.

Hierarchical Partition Keys

  • What it is: Use nested JSON fields to create multi-level keys.
  • Example: /genre/region → "Sci-Fi/UK", "Romance/USA"
  • Why it helps: Data is distributed according to a real-world structure, reflecting categories and subcategories.
  • Analogy: Think of sorting books first by genre, then by region — you avoid one big pile and make everything easier to find.

Why These Strategies Matter

  • Hot partitions can quietly crush performance, causing slow queries and throttled writes.
  • Using high-cardinality, time-based, or hierarchical keys spreads data across physical partitions.
  • This ensures Cosmos DB can scale efficiently and your app stays fast and responsive.

Summary

In a nutshell, use these solutions to help distribute the load and prevent bottlenecks. Hot partitions can silently crush performance. Smart partition design is the key.

Resources