Introduction

RD_KAFKA_PARTITION_UA in librdkafka means "unassigned partition." When you produce a message with this special partition value, you are not telling Kafka to choose the partition magically at the broker. You are telling librdkafka to run its configured partitioner and decide the partition on the client side.

What the Constant Means

In librdkafka, RD_KAFKA_PARTITION_UA is the special partition value used when the application does not explicitly name a partition. The producer then uses its partitioning logic to choose one.

That matters because Kafka partitioning affects:

• message ordering
• key affinity
• load distribution
• consumer parallelism

So "unassigned" does not mean "no partition." It means "let the producer's partitioner assign one."

Producing with RD_KAFKA_PARTITION_UA

Here is a simple C example:

1#include <stdio.h>
2#include <string.h>
3#include <librdkafka/rdkafka.h>
4
5int main(void) {
6    char errstr[512];
7    rd_kafka_conf_t *conf = rd_kafka_conf_new();
8
9    if (rd_kafka_conf_set(conf, "bootstrap.servers", "localhost:9092",
10                          errstr, sizeof(errstr)) != RD_KAFKA_CONF_OK) {
11        fprintf(stderr, "config error: %s\n", errstr);
12        return 1;
13    }
14
15    rd_kafka_t *rk = rd_kafka_new(RD_KAFKA_PRODUCER, conf, errstr, sizeof(errstr));
16    if (!rk) {
17        fprintf(stderr, "producer creation failed: %s\n", errstr);
18        return 1;
19    }
20
21    if (rd_kafka_producev(
22            rk,
23            RD_KAFKA_V_TOPIC("orders"),
24            RD_KAFKA_V_PARTITION(RD_KAFKA_PARTITION_UA),
25            RD_KAFKA_V_MSGFLAGS(RD_KAFKA_MSG_F_COPY),
26            RD_KAFKA_V_VALUE("hello", 5),
27            RD_KAFKA_V_END) != RD_KAFKA_RESP_ERR_NO_ERROR) {
28        fprintf(stderr, "produce failed: %s\n",
29                rd_kafka_err2str(rd_kafka_last_error()));
30    }
31
32    rd_kafka_flush(rk, 5000);
33    rd_kafka_destroy(rk);
34    return 0;
35}

The key detail is that the producer still assigns a real partition before sending the record.

How the Partitioner Uses Keys

When a message has a key, the configured partitioner usually uses that key to select a partition deterministically. That means records with the same key tend to land in the same partition, which preserves per-key ordering.

If there is no key, the partitioner may distribute messages differently depending on configuration and partitioner choice. The important thing is that the client, not the broker, makes the decision.

So a good mental model is:

• explicit partition number: you choose
• 'RD_KAFKA_PARTITION_UA: librdkafka chooses'

Why This Is Useful

Using RD_KAFKA_PARTITION_UA is usually the right default when:

• you want key-based routing
• you do not want to hard-code partition numbers
• you want load spread to follow the configured partitioner

It keeps the producer logic simpler and avoids embedding partition assumptions into application code.

When Explicit Partitions Make Sense

There are still cases where specifying a partition explicitly is appropriate:

• testing a specific partition path
• sending data to a known partition for operational reasons
• reproducing a partition-specific issue

But for ordinary business events, letting the configured partitioner decide is usually better than hard-coding numbers.

Do Not Confuse This with Broker-Side Assignment

One common misunderstanding is that RD_KAFKA_PARTITION_UA tells the Kafka broker to assign a partition. In normal producer usage, the partition decision is made by librdkafka before the request is sent.

That distinction matters because:

• the configured client partitioner affects the result
• key hashing happens on the producer side
• changing producer configuration can change distribution behavior

A Keyed Produce Example

With a key, the partitioner can keep related records together:

1rd_kafka_producev(
2    rk,
3    RD_KAFKA_V_TOPIC("orders"),
4    RD_KAFKA_V_PARTITION(RD_KAFKA_PARTITION_UA),
5    RD_KAFKA_V_KEY("customer-42", strlen("customer-42")),
6    RD_KAFKA_V_VALUE("order-created", strlen("order-created")),
7    RD_KAFKA_V_MSGFLAGS(RD_KAFKA_MSG_F_COPY),
8    RD_KAFKA_V_END
9);

In practice, repeated records with the same key usually map to the same partition as long as the partition count and partitioner behavior are stable.

Common Pitfalls

• Thinking "UA" means the message is sent without a partition decision.
• Assuming the broker chooses the partition when the client partitioner actually does.
• Forgetting that keyed and unkeyed messages can distribute differently.
• Hard-coding partition numbers when ordinary partitioner behavior would be simpler and safer.
• Changing partition counts or partitioner configuration without considering how message distribution will change.

Summary

• 'RD_KAFKA_PARTITION_UA means "unassigned partition" from the application's point of view.'
• Librdkafka uses its configured partitioner to choose the actual partition.
• Keys usually make partition selection deterministic for related messages.
• This is usually the right default when you do not need a hard-coded partition number.
• The partition decision happens on the producer side, not as a broker-side mystery step.