{
    "slug": "topic_partition",
    "term": "Topics & Partitions",
    "category": "messaging",
    "difficulty": "intermediate",
    "short": "Kafka topics are divided into partitions — the unit of parallelism and ordering. More partitions = more parallelism; partition key determines which partition a record lands in.",
    "long": "Topic: a named stream of records. Partition: an ordered, immutable log. Records appended with offset. Multiple partitions per topic: parallel reads/writes. Partition assignment: by key hash (same key → same partition → ordering), round-robin (no key → load balanced → no ordering), custom partitioner. Replication: each partition has one leader and N-1 followers. Leader handles reads/writes; followers replicate. Partition count: set at creation (can increase, never decrease). More partitions → more parallelism → more overhead (file handles, memory). Typical: 3-12 partitions for throughput, 1 for strict ordering.",
    "aliases": [],
    "tags": [
        "messaging",
        "kafka",
        "partitions",
        "topics"
    ],
    "misconception": "More partitions is always better — each partition has overhead (file handle, memory, rebalancing cost). Start with 3-6 and increase if needed.",
    "why_it_matters": "Partition count determines maximum parallelism — it's the most important Kafka sizing decision and can't easily be reduced after creation.",
    "common_mistakes": [
        "Too many partitions for the workload — overhead without benefit.",
        "Changing partition count without updating consumers — key routing changes.",
        "No replication in production — single partition leader = single point of failure."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "kafka_concepts",
        "consumer_group",
        "message_ordering",
        "at_least_once_delivery"
    ],
    "prerequisites": [
        "kafka_concepts",
        "consumer_group"
    ],
    "refs": [
        "https://kafka.apache.org/documentation/#intro_topics"
    ],
    "bad_code": "# 1 partition — no parallelism:\nkafka-topics --create --topic orders --partitions 1 --replication-factor 1\n# 1000 partitions — unnecessary overhead",
    "good_code": "# Balanced: 6 partitions, 3 replicas:\nkafka-topics --create --topic orders --partitions 6 --replication-factor 3\n\n# PHP producer with partition key:\n$conf->set('partitioner', 'consistent_random'); // Same key = same partition\n$producer->produce(RD_KAFKA_PARTITION_UA, 0, $payload, $orderId); // Key = orderId",
    "quick_fix": "Start with 3-6 partitions per topic. Set replication-factor=3 for production. Use entity ID as partition key for ordering. Monitor partition lag per consumer group.",
    "severity": "info",
    "effort": "medium",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/topic_partition",
        "html_url": "https://codeclaritylab.com/glossary/topic_partition",
        "json_url": "https://codeclaritylab.com/glossary/topic_partition.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Topics & Partitions](https://codeclaritylab.com/glossary/topic_partition) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/topic_partition"
            }
        }
    }
}