Event Hub Partitions and Partition Keys
Partitions are the foundation of Azure Event Hub's ability to handle millions of events per second. Understanding how partitions work — and how partition keys control event routing — is essential for building high-throughput, ordered event streaming solutions.
What Is a Partition
A partition is an ordered, immutable sequence of events. Think of it as a separate lane on a highway. Multiple lanes let more cars travel simultaneously, and each lane maintains the order of cars within it.
An Event Hub divides its total capacity across all partitions. Each partition receives its own subset of events and stores them in the order they arrive.
Event Hub: 4 Partitions Partition 0: [E-A1]---[E-A2]---[E-A3]---[E-A4] ← Events for Customer A Partition 1: [E-B1]---[E-B2]---[E-B3] ← Events for Customer B Partition 2: [E-C1]---[E-C2]---[E-C3]---[E-C4] ← Events for Customer C Partition 3: [E-D1] ← Events for Customer D Each partition: ordered, independent, parallelizable
Why Partitions Enable Scale
Without partitions, a single stream would become a bottleneck at high volume. With partitions, many producers write simultaneously and many consumers read simultaneously — each handling different partitions.| Without Partitions | With Partitions |
|---|---|
| All events queue in one sequence | Events spread across multiple sequences |
| Single writer bottleneck | Multiple writers in parallel |
| Single reader throughput | Multiple readers, one per partition |
| One reader processes all events | Each reader handles its partition subset |
Partition Count Rules
You set the partition count when creating an Event Hub. This count cannot be changed after creation (for Standard tier). Premium and Dedicated tiers support dynamic partition count changes.| Tier | Minimum Partitions | Maximum Partitions |
|---|---|---|
| Basic | 1 | 32 |
| Standard | 1 | 32 |
| Premium | 1 | 100 |
| Dedicated | 1 | 1024 |
Choose the partition count based on peak expected parallelism. If you expect at most 10 independent consumers reading simultaneously, 10 partitions is a good starting point.
What Is a Partition Key
A partition key is a string value you assign to an event when sending it. Event Hub hashes the partition key and maps the hash to a specific partition number. All events with the same partition key always go to the same partition, guaranteeing their order relative to each other.Producer sends events with partition keys: Event 1 → partitionKey: "customer-101" Event 2 → partitionKey: "customer-202" Event 3 → partitionKey: "customer-101" Event 4 → partitionKey: "customer-303" Event 5 → partitionKey: "customer-101" Event Hub hashing: "customer-101" → hash → Partition 0 "customer-202" → hash → Partition 1 "customer-303" → hash → Partition 2 Result in partitions: Partition 0: [Event 1][Event 3][Event 5] ← All customer-101 events in order Partition 1: [Event 2] ← customer-202 events Partition 2: [Event 4] ← customer-303 events
When Order Matters: The Bank Account Example
A banking application processes account transactions. The events for one account must be processed in order — a deposit followed by a withdrawal is valid; the reverse might cause an overdraft error.Account 12345 transactions: Event A: Deposit $500 → partitionKey: "account-12345" Event B: Withdrawal $200 → partitionKey: "account-12345" Event C: Deposit $100 → partitionKey: "account-12345" All three go to Partition 2 (same hash for same key) Partition 2: [Deposit $500][Withdrawal $200][Deposit $100] Consumer reads them in exact order. Balance calculation is correct.
If no partition key was used, these three events might land on different partitions and arrive out of order at the consumer.
No Partition Key: Round-Robin Distribution
When you send an event without a partition key, Event Hub distributes events in round-robin order across partitions. This maximizes throughput but sacrifices order guarantees.No partition key → round-robin: Event 1 → Partition 0 Event 2 → Partition 1 Event 3 → Partition 2 Event 4 → Partition 3 Event 5 → Partition 0 (cycles back) Best for: High-volume telemetry where order across events doesn't matter Avoid for: Related events that must be processed sequentially
Sending Events with a Partition Key in Code
C# Example
await using var producerClient = new EventHubProducerClient(
connectionString, "myEventHub");
// Create a batch with a specific partition key
var options = new CreateBatchOptions
{
PartitionKey = "customer-101"
};
using EventDataBatch eventBatch = await producerClient.CreateBatchAsync(options);
eventBatch.TryAdd(new EventData("Transaction: Deposit $500"));
eventBatch.TryAdd(new EventData("Transaction: Withdrawal $200"));
// All events in this batch go to the same partition
await producerClient.SendAsync(eventBatch);
Python Example
async with EventHubProducerClient.from_connection_string(
conn_str=connection_string,
eventhub_name="myEventHub"
) as producer:
event_data_batch = await producer.create_batch(
partition_key="customer-101"
)
event_data_batch.add(EventData("Transaction: Deposit $500"))
event_data_batch.add(EventData("Transaction: Withdrawal $200"))
await producer.send_batch(event_data_batch)
Sending to a Specific Partition ID Directly
You can also send events to a specific partition by its numeric ID instead of using a key. This gives explicit control but bypasses the hash routing.
// Send directly to partition "2"
var options = new CreateBatchOptions
{
PartitionId = "2"
};
Use this approach only when your application manages partition assignment logic itself. For most cases, partition keys are the better choice.
Partition Key vs Partition ID vs No Key
| Approach | How Routing Works | Order Guarantee | Best For |
|---|---|---|---|
| Partition Key | Consistent hash maps key to partition | Within same key | Related events (per user, per order) |
| No Key (round-robin) | Distributed evenly across partitions | None | Independent high-volume events |
| Partition ID | Goes to the exact named partition | Within that partition | Custom partition management |
Choosing the Right Partition Key
A good partition key produces even distribution across partitions. A bad partition key creates hot partitions — one partition receives most of the events while others sit idle.BAD partition key: "region" with values "US", "EU", "Asia" → Only 3 distinct values → Only 3 partitions active out of 32 → Severe imbalance GOOD partition key: "customerId" with thousands of distinct values → Many distinct values → Events spread across all 32 partitions → Even throughput distribution
Guidelines for Partition Key Selection
| Rule | Explanation |
|---|---|
| Use high-cardinality keys | More unique values = better distribution |
| Use keys that group related events | Same entity events must land on same partition for ordering |
| Avoid time-based keys | Creates hot partition as current-time key dominates |
| Avoid status-based keys | Few status values = few active partitions |
| Test distribution before production | Verify all partitions receive roughly equal load |
Partition and Consumer Parallelism
Each partition can have at most one active reader per consumer group. This means the number of partitions sets the maximum degree of consumer parallelism.Event Hub: 4 Partitions Consumer Group: "analytics" Maximum parallel consumers = 4 Consumer 1 → reads Partition 0 Consumer 2 → reads Partition 1 Consumer 3 → reads Partition 2 Consumer 4 → reads Partition 3 Adding Consumer 5 → waits idle (no partition available)
To increase parallelism, increase the partition count. But remember: partition count is fixed at creation time for Standard tier, so plan ahead.