Redpanda doesn’t just store your messages; it enforces a surprisingly strict set of rules on your topic names to keep its internal state consistent and performant.
Let’s see Redpanda in action with topic names. Imagine we have a running Redpanda cluster. We can interact with it using rpk, the Redpanda command-line tool.
First, let’s try creating a topic with a valid name:
rpk topic create my-valid-topic --partitions 3 --replication-factor 3
This command works perfectly. Redpanda creates my-valid-topic with 3 partitions and a replication factor of 3. Now, let’s try something that violates the rules.
rpk topic create "topic with spaces"
This will fail. Redpanda will return an error: topic name contains invalid characters. This illustrates that spaces are not allowed.
What about case sensitivity?
rpk topic create My-Topic
rpk topic create my-topic
These two commands will create distinct topics because Redpanda topic names are case-sensitive. My-Topic and my-topic are treated as entirely different entities.
Now, let’s consider the constraints:
-
Character Set: Topic names can only contain ASCII alphanumeric characters (
a-z,A-Z,0-9), periods (.), underscores (_), and hyphens (-). This is the most fundamental rule. Any other character will cause an immediate rejection. -
Length: Topic names must be between 1 and 249 characters long. This is a practical limit to prevent extremely long, unmanageable names and to ensure efficient storage and lookup within Redpanda’s internal metadata.
-
Case Sensitivity: As demonstrated,
MyTopicandmytopicare distinct. This is crucial to remember when designing your topic naming strategy, especially if you’re migrating from systems where case might be ignored. -
No Leading/Trailing Dots or Underscores: While dots and underscores are allowed within a name, a topic name cannot start or end with a
.or_. For example,_my_topicormy_topic.are invalid. -
No Consecutive Dots or Underscores: You cannot have two or more consecutive dots or underscores.
my..topicormy__topicare forbidden.
These constraints aren’t arbitrary. They’re designed to map directly to how Redpanda (and Kafka, which it emulates) organizes topics internally. Topic names are used as keys in various internal data structures, and these restrictions ensure that these keys are valid, sortable, and don’t cause issues with string parsing or filesystem representations (though Redpanda doesn’t use the filesystem directly for topic data, the principle of well-formed keys remains). The 249-character limit is also a common Kafka-derived constraint, ensuring compatibility and predictable metadata handling.
The common pitfalls often stem from assuming broader character support or case-insensitivity. Developers migrating from other messaging systems or databases might be accustomed to more permissive naming rules. The 249-character limit is rarely hit in practice, but exceeding it will result in a topic name is too long error.
The most surprising thing about Redpanda’s topic name constraints is how strictly they are enforced at creation time, but how Redpanda’s internal mechanisms can actually tolerate certain characters if they are part of a topic name that already exists when Redpanda starts up. However, attempting to create a new topic with invalid characters will always fail. This means if you have a pre-existing topic with, say, a space in its name (perhaps from an older, less strict version or a different tool), Redpanda might continue to serve it, but you absolutely cannot create another one like it.
The next challenge you’ll encounter is understanding how these topic names interact with Redpanda’s schema registry and topic configuration options.