Topic Partition

A topic partition is one ordered, append-only log within a Kafka topic. A topic is spread over a number of partitions placed on different brokers, and each record written to the topic is appended to exactly one of them, receiving an offset — its position in that log. Descriptions follow Apache Kafka 4.3.X documentation, checked in September 2026.

One unit, three jobs

Because one structure carries all three, the two numbers you pick when creating a topic — the key and the partition count — settle questions that feel unrelated. That is the source of most Kafka design mistakes.

Ordering belongs to the partition; the key is how you land in one

Getting this the right way round prevents a family of mistakes. The guarantee is a property of the partition: records in one partition are delivered in the order they were appended, and across partitions there is no defined order at all. The key does not create ordering — it decides which partition a record lands in, and so which records end up sharing a partition’s guarantee.

Two corrections follow from putting it that way.

• Unkeyed records are not unordered. They are distributed across partitions, and within whichever partition each lands in, order still holds. What you lose is control over which records share a partition — so two related events may or may not be ordered relative to each other, and you cannot arrange for them to be. “No ordering at all” overstates it and leads people to believe a single-partition topic without keys has no guarantee, which is wrong.
• A shared key is not automatically sufficient. It is sufficient while the mapping from key to partition is stable and actually in force. A producer that sets the partition explicitly overrides the key. A custom partitioner can route the same key elsewhere, and two producers configured differently can disagree. And adding partitions changes the mapping, so records with one key written before and after the change sit in different partitions — with no ordering between them, permanently, for the records already written.

So the practical test has two parts. Name the two events that must never be seen out of order, and check that they will land in the same partition — which means checking the key and that nothing between the application and the broker decides the partition some other way. Where the requirement is absolute and the topic may be expanded, the durable arrangement is to pin the mapping deliberately rather than to rely on the default hash of a key surviving a capacity change.

Keying by customer rather than by order still concentrates a busy customer’s traffic on one partition, which is the throughput cost of a wider ordering scope.

The count is hard to change later

• Too few caps how many consumers can work in parallel, and idle consumers in a group are the visible symptom.
• Too many multiplies files, connections, and per-partition overhead on the brokers, and makes each partition’s traffic thinner.
• Adding partitions later changes where keys land. Records already written stay where they are, so a key can have older records in one partition and newer ones in another — and the ordering guarantee, which is per partition, no longer spans that key’s history.

A workable order of decisions: choose the key from what must stay ordered together, then set the partition count from the throughput and consumer parallelism you expect, with room to grow — because growing it is the part that has consequences. How partitions interact with replication, retention, and consumer groups is worked through in Kafka as a Log.

References: Apache Kafka documentation, Introduction; Apache Kafka documentation, Design.