---
title: "Choose the partition key for the order you · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/publishing-events/partition-keys
id: EVT-9
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 860
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Choose the partition key for the order you need

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Publishing events](https://agentwranglers.se/playbook/events/publishing-events.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-9
- Level: Recommended
- Chapter: [Publishing events](https://agentwranglers.se/playbook/events/publishing-events.md)
- Rule: Set a message key on every event whose order matters, such as the order ID or the account ID. A broker keeps order only inside one partition, and the key decides the partition.
- Check: A unit test publishes three events for one order through the producer code, and all three carry the order ID as their key. On staging, a consumer reads 1,000 events for 10 orders and finds each order's events in write order.
- How: Kafka and similar logs hash the key to pick a partition, so all events with one key arrive in the order they were written. Events without a key spread over partitions and lose their order. Pick the narrowest key that still covers what must stay in order. An account ID keeps every event of a large customer on one partition, and one busy key then slows that whole partition. Set enough partitions for the consumers you plan, because adding partitions later moves keys to other partitions and breaks order for a while. Queues that are not logs, such as Amazon SQS FIFO queues, use a message group ID the same way. Consumers still guard against old events, as [Don't rely on event order](https://agentwranglers.se/playbook/events/consuming-events/event-order.md) says.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### JavaScript example

```js
await producer.send({
  topic: 'shop.orders',
  messages: [{ key: order.id, value: JSON.stringify(envelope('com.example.shop.order.paid.v1', { orderId: order.id })) }],
});
```

### Python example

```python
producer.produce(
    "shop.orders",
    key=order.id,
    value=json.dumps(envelope("com.example.shop.order.paid.v1", {"orderId": order.id}, SCHEMA_URL)),
)
```

## Sources

- [Apache Kafka design, the producer and partitions](https://kafka.apache.org/43/design/design/)

## Related rules

- EVT-12 [Don't rely on event order](https://agentwranglers.se/playbook/events/consuming-events/event-order.md) in Integration and events
- EVT-13 [Alert when a consumer falls behind](https://agentwranglers.se/playbook/events/consuming-events/consumer-lag.md) in Integration and events

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/events/publishing-events/partition-keys">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Cap and watch replication slots](https://agentwranglers.se/playbook/events/publishing-events/replication-slot-limits.md)
- Next: [Deliver events through a shared channel](https://agentwranglers.se/playbook/events/publishing-events/shared-pubsub.md)
- [Publishing events](https://agentwranglers.se/playbook/events/publishing-events.md)