How to Configure Kafka Topic Partitions and Replication per MQTT Mapping in HiveMQ

This article explains the current capabilities and limitations of the HiveMQ Enterprise Extension for Kafka regarding topic partitioning and replication settings. It also outlines workarounds and guidance for use cases where per-mapping topic configurations are required.

Instructions

Important

Per-mapping topic partition and replication factor settings are not currently supported.
HiveMQ Kafka Extension applies topic creation settings globally. There is no native support for specifying these values on a per-<mqtt-kafka-mapping> basis.

Scenario

You want to send MQTT messages from specific topics (e.g., measurements) to Kafka and control:

Partition count
Replication factor
…but only for some mappings, not globally.

Example goal:

<mqtt-kafka-mapping>
  <id>measurements</id>
  <!-- would like to override partitions/replication here -->
</mqtt-kafka-mapping>

But this is not supported.

Current Behavior

By default, Kafka topic creation uses:

kafka.topic.default.replication.factor = 3
kafka.topic.default.partitions = 3

These settings apply to all auto-created topics and cannot be configured on a per-mapping basis in the current version.

Workarounds

Pre-create Topics in Kafka
Define your desired partition count and replication factor directly in Confluent Cloud or your Kafka cluster. HiveMQ will use the existing topic settings and skip topic creation.
Use Global Defaults Only
Use the default replication factor and partition count values (3) globally. Unfortunately, there's no per-mapping override option available right now.

Summary

Capability	Supported?

Capability	Supported?
Global default partitions/replication	Yes
Per-mapping partitions/replication	No
Manual topic setup in Kafka	Yes