# Manage Topics > For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt) --- title: Manage Topics latest-redpanda-tag: v26.2.1 latest-console-tag: v3.10.0 latest-operator-version: v26.2.1 # EOL = End-of-Life (support lifecycle status) page-is-nearing-eol: "false" page-is-past-eol: "false" page-eol-date: July 28, 2027 latest-connect-version: 4.105.0 docname: manage-topics/config-topics page-component-name: streaming page-version: "26.2" page-component-version: "26.2" page-component-title: Streaming page-relative-src-path: manage-topics/config-topics.adoc page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/develop/pages/manage-topics/config-topics.adoc description: Learn how to create topics, update topic configurations, and delete topics or records. page-git-created-date: "2026-03-31" page-git-modified-date: "2026-08-12" support-status: supported --- Topics provide a way to organize events in a data streaming platform. When you create a topic, the default cluster-level topic configurations are applied using the cluster configuration file, unless you specify different configurations. The following table shows the default cluster-level properties and their equivalent topic-level properties: | Cluster property | Default | Topic property | | --- | --- | --- | | log_cleanup_policy | delete | cleanup.policy | | retention_bytes | null (no limit) | retention.bytes | | log_retention_ms | 604800000 ms (1 week) | retention.ms | | log_segment_ms | null (no limit) | segment.ms | | log_segment_size | 134217728 bytes (128 MiB) | segment.bytes | | log_compression_type | producer | compression.type | | log_message_timestamp_type | CreateTime | message.timestamp.type | | kafka_batch_max_bytes | 1048576 bytes (1 MiB) | max.message.bytes | | write_caching_default | false | write.caching | These default settings are best suited to a one-broker cluster in a development environment. To learn how to modify the default cluster-wide configurations, see [Configure Cluster Properties](https://docs.redpanda.com/streaming/current/manage/cluster-maintenance/cluster-property-configuration/). Even if you set default values that work for most topics, you may still want to change some properties for a specific topic. > 📝 **NOTE** > > For details about topic properties, see [Topic Configuration Properties](https://docs.redpanda.com/streaming/current/reference/properties/topic-properties/). ## [](#create-a-topic)Create a topic Creating a topic can be as simple as specifying a name for your topic on the command line. For example, to create a topic named `xyz`, run: ```bash rpk topic create xyz ``` This command creates a topic named `xyz` with one partition and one replica, because these are the default values set in the cluster configuration file. Replicas are copies of partitions that are distributed across different brokers, so if one broker goes down, other brokers still have a copy of the data. ### [](#choose-the-number-of-partitions)Choose the number of partitions A partition acts as a log file where topic data is written. Dividing topics into partitions allows producers to write messages in parallel and consumers to read messages in parallel. The higher the number of partitions, the greater the throughput. > 💡 **TIP** > > As a general rule, select a number of partitions that corresponds to the maximum number of consumers in any consumer group that will consume the data. For example, suppose you plan to create a consumer group with 10 consumers. To create topic `xyz` with 10 partitions, run: ```bash rpk topic create xyz -p 10 ``` ### [](#choose-the-replication-factor)Choose the replication factor The default replication factor in the cluster configuration is set to 1. By choosing a replication factor greater than 1, you ensure that each partition has a copy of its data on at least one other broker. One replica acts as the leader, and the other replicas are followers. To specify a replication factor of 3 for topic `xyz`, run: ```bash rpk topic create xyz -r 3 ``` > 📝 **NOTE** > > The replication factor must be an odd number. Redpanda Data recommends a replication factor of 3 for most use cases. Administrators may set a minimum required replication factor for any new topic in the cluster through the cluster-level [`minimum_topic_replications`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#minimum_topic_replications) property. > 💡 **TIP** > > If you enable [Tiered Storage](https://docs.redpanda.com/streaming/current/manage/tiered-storage/) on a topic, you can then use [topic recovery](https://docs.redpanda.com/streaming/current/manage/disaster-recovery/topic-recovery/) to restore data for a deleted topic. ### [](#choose-a-storage-mode)Choose a storage mode Starting in Redpanda v26.1, you can set the `redpanda.storage.mode` topic property to control how a topic stores data: | Value | Behavior | | --- | --- | | unset (default) | Legacy behavior. Tiered Storage is controlled by the redpanda.remote.read and redpanda.remote.write topic properties and their cluster-level defaults (cloud_storage_enable_remote_read and cloud_storage_enable_remote_write). | | local | Topic data is stored only on the broker’s local disk. Object storage upload is disabled for the topic, regardless of redpanda.remote.read and redpanda.remote.write values. | | tiered | Data is stored on local disk and uploaded to object storage. Enables Tiered Storage for the topic regardless of redpanda.remote.read and redpanda.remote.write values. Starting in Redpanda v26.2, Tiered Storage is available in two versions (tiered_v1 and tiered_v2). See Choose a Tiered Storage version. | | cloud | Data is stored durably in object storage using the Cloud Topics architecture. Local storage is used only as a write buffer. See Manage Cloud Topics. | To set the storage mode at topic creation time: ```bash rpk topic create -c redpanda.storage.mode=tiered ``` When `redpanda.storage.mode` is set to `local`, `tiered`, or `cloud`, the `redpanda.remote.read` and `redpanda.remote.write` topic properties have no effect on the topic. Starting in Redpanda v26.2, the `tiered` value is an alias that resolves to one of two Tiered Storage versions when the topic is created. The [`default_redpanda_storage_mode_tiered_impl`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#default_redpanda_storage_mode_tiered_impl) cluster property selects the version (`tiered_v1` by default). To select the version explicitly for a single topic, set both `redpanda.storage.mode` and `redpanda.storage.mode.impl` when you create the topic: ```bash rpk topic create -c redpanda.storage.mode=tiered -c redpanda.storage.mode.impl=tiered_v2 ``` The `redpanda.storage.mode.impl` property reports the exact implementation of every topic’s storage mode and is read-only after topic creation. For details, see [Choose a Tiered Storage version](https://docs.redpanda.com/streaming/current/manage/tiered-storage/#tiered-storage-versions). To apply a default storage mode to all new topics in a cluster, set the `default_redpanda_storage_mode` cluster property: ```bash rpk cluster config set default_redpanda_storage_mode=tiered ``` To set `local` as the default storage mode for all new topics in a cluster: ```bash rpk cluster config set default_redpanda_storage_mode=local ``` If `default_redpanda_storage_mode` is not configured (the default), new topics use `unset` mode and Tiered Storage behavior is inherited from the cluster-level `cloud_storage_enable_remote_write` and `cloud_storage_enable_remote_read` properties. ## [](#update-topic-configurations)Update topic configurations After you create a topic, you can update the topic property settings for all new data written to it. For example, you can add partitions or change the cleanup policy. ### [](#add-partitions)Add partitions You can assign a certain number of partitions when you create a topic, and add partitions later. For example, suppose you add brokers to your cluster, and you want to take advantage of the additional processing power. To increase the number of partitions for existing topics, run: ```bash rpk topic add-partitions [TOPICS...] --num [#] ``` Note that `--num <#>` is the number of partitions to _add_, not the total number of partitions. > 📝 **NOTE** > > If a topic already has messages and you add partitions, the existing messages won’t be redistributed to the new partitions. If you require messages to be redistributed, then you must create a new topic with the new partition count, then stream the messages from the old topic to the new topic so they are appropriately distributed according to the new partition hashing. ### [](#reduce-the-number-of-partitions)Reduce the number of partitions You cannot reduce the number of partitions on an existing topic. The Kafka API does not support it: a record’s partition is chosen when the record is produced, and records that have already been written stay in the partition where they landed, so removing a partition would orphan its data. Redpanda assigns a record that has a key to a partition by hashing the key, and leaves a record without a key to the producer’s partitioner, which usually spreads such records across all available partitions. To move a topic’s data to fewer partitions, copy it to a new topic and switch your clients over. Before you start, check that your applications can tolerate the following: - **Duplicates**: Redpanda Connect delivers records at least once, so a restart or a retry during the copy can write the same record to the new topic twice. A lag of zero shows only how far the copy has committed, not that the new topic is free of duplicates. Either make your consumers idempotent, or deduplicate on a record ID after the copy. - **Ordering**: records keep their keys, so all records for a key still land on one partition and keep their order relative to each other, but the global order of records across partitions is not preserved. - **Retention**: the copy starts at the oldest record that is still retained. Records that retention or compaction has already removed cannot be copied, and both keep running during the copy, so complete the copy well within the topic’s retention period. - **Consumer offsets**: consumer group offsets are stored per topic, so the offsets your consumers committed on the original topic do not carry over. Each consumer starts from the beginning of the new topic and replays what the copy wrote, unless you set its offsets explicitly with `rpk group seek`. - **Write downtime**: producers must stop writing to the original topic before you switch clients over, so plan a window in which the topic accepts no writes. The following procedure reduces a topic named `orders` from three partitions to one. 1. Check the configuration of the original topic so that you can recreate it. Note the replication factor, and every row whose `SOURCE` is `DYNAMIC_TOPIC_CONFIG`, which is an override you must set on the new topic: ```bash rpk topic describe orders ``` Example output (abbreviated) ```bash SUMMARY ======= NAME orders PARTITIONS 3 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DEFAULT_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.local.target.ms 86400000 DEFAULT_CONFIG retention.ms 604800000 DYNAMIC_TOPIC_CONFIG segment.bytes 134217728 DEFAULT_CONFIG ``` Here, only `retention.ms` is an override. If the topic has Tiered Storage settings, a custom cleanup policy, or other overrides, carry all of them over: a new topic created without them silently falls back to the cluster defaults. 2. Create the new topic with the target number of partitions, the replication factor of the original topic, and each override from the previous step: ```bash rpk topic create orders-reduced --partitions 1 --replicas 1 --topic-config retention.ms=604800000 ``` Example output ```bash TOPIC STATUS orders-reduced OK ``` 3. Copy the data with a [Redpanda Connect](https://docs.redpanda.com/connect/get-started/about/) pipeline. This configuration reads all records that are still available in the original topic and preserves record keys, so records for the same key land on the same partition of the new topic: `reduce-partitions.yaml` ```yaml input: redpanda: seed_brokers: [""] topics: ["orders"] consumer_group: orders-to-orders-reduced start_offset: earliest output: redpanda: seed_brokers: [""] topic: orders-reduced key: ${! @kafka_key } ``` Give the consumer group a name that is unique to this copy, such as `-to-`. `start_offset: earliest` applies only when the group has no committed offset, so a group name that has been used before resumes from where it left off and skips records. ```bash rpk connect run reduce-partitions.yaml ``` Example output ```bash level=info msg="Launching a Redpanda Connect instance, use CTRL+C to close" level=info msg="Output type redpanda is now active" level=info msg="Input type redpanda is now active" ``` 4. Stop the producers that write to the original topic. Leave the pipeline running so that it copies the last records they wrote. 5. Wait for the copy to drain. It is complete when the consumer group reports a `LAG` of `0` for every partition of the original topic: ```bash rpk group describe orders-to-orders-reduced ``` Example output ```bash GROUP orders-to-orders-reduced COORDINATOR-NODE 0 COORDINATOR-PARTITION __consumer_offsets/0 STATE Stable BALANCER cooperative-sticky MEMBERS 1 TOTAL-LAG 0 TOPIC PARTITION CURRENT-OFFSET LOG-START-OFFSET LOG-END-OFFSET LAG MEMBER-ID CLIENT-ID HOST orders 0 3 0 3 0 redpanda-connect-15d7a80f-590f-4cde-bc16-4854fa2754 redpanda-connect 10.0.0.1 orders 1 3 0 3 0 redpanda-connect-15d7a80f-590f-4cde-bc16-4854fa2754 redpanda-connect 10.0.0.1 orders 2 3 0 3 0 redpanda-connect-15d7a80f-590f-4cde-bc16-4854fa2754 redpanda-connect 10.0.0.1 ``` 6. Compare the record counts of the two topics. For each topic, the number of available records is the sum of `HIGH-WATERMARK` minus `LOG-START-OFFSET` across its partitions. A higher count on the new topic means the copy wrote duplicates: ```bash rpk topic describe orders -p rpk topic describe orders-reduced -p ``` Example output ```bash PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 0 1 [0] 0 3 1 0 1 [0] 0 3 2 0 1 [0] 0 3 PARTITION LEADER EPOCH REPLICAS LOG-START-OFFSET HIGH-WATERMARK 0 0 1 [0] 0 9 ``` Nine records across the three original partitions, and the same nine on the single partition of the new topic. 7. Point your producers and consumers at the new topic. Consumers start from the beginning of the new topic unless you set their offsets with `rpk group seek`. 8. Stop the pipeline with Ctrl+C. 9. When you no longer need the original topic, delete it to reclaim storage. See [Delete a topic](#delete-a-topic). > ⚠️ **CAUTION** > > Do not delete the original topic until the new topic holds the data you expect and your consumers are running against it. Deleting a topic deletes its data. ### [](#change-the-replication-factor)Change the replication factor Suppose you create a topic with the default replication factor of 1 (which is specified in the cluster properties configuration file). Now you want to change the replication factor to 3, so you can have two backups of topic data in case a broker goes down. To set the replication factor to 3, run: ```bash rpk topic alter-config [TOPICS...] --set replication.factor=3 ``` > 📝 **NOTE** > > The replication factor can’t exceed the number of Redpanda brokers. If you try to set a replication factor greater than the number of brokers, the request is rejected. ### [](#change-the-storage-mode)Change the storage mode You can change a topic’s `redpanda.storage.mode` after creation, with the following restrictions: | From | To | Permitted | Notes | | --- | --- | --- | --- | | local | tiered (v1) | Yes | Enables Tiered Storage for the topic. Object storage must be configured. | | tiered (v1) | local | With caution | Disables object storage uploads. Redpanda strongly recommends against repeatedly toggling this setting, as it can result in data gaps in Tiered Storage. | | cloud | tiered (v2) | Yes | Starting in Redpanda v26.2. All brokers must run v26.2 or later. | | tiered (v2) | cloud | Yes | Starting in Redpanda v26.2. | | tiered (v1) | tiered (v2) | No | Topics cannot be converted between Tiered Storage versions, in either direction. | | local | tiered (v2) | No | | | Any other mode | cloud | No | Cloud Topics can otherwise only be set at topic creation time. | | cloud | local or tiered (v1) | No | A Cloud Topic cannot be converted to a local or Tiered Storage v1 topic. | When you change the storage mode, you always set the `redpanda.storage.mode` property. The `tiered` value resolves to the version selected by the [`default_redpanda_storage_mode_tiered_impl`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#default_redpanda_storage_mode_tiered_impl) cluster property, so, for example, converting a `cloud` topic to Tiered Storage v2 requires `default_redpanda_storage_mode_tiered_impl=tiered_v2`. The `redpanda.storage.mode.impl` property cannot be changed after topic creation. See [Choose a Tiered Storage version](https://docs.redpanda.com/streaming/current/manage/tiered-storage/#tiered-storage-versions). For example, to transition an existing local topic to Tiered Storage: ```bash rpk topic alter-config --set redpanda.storage.mode=tiered ``` > 📝 **NOTE** > > This example requires [`default_redpanda_storage_mode_tiered_impl`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#default_redpanda_storage_mode_tiered_impl) to be `tiered_v1` (the default). If the cluster default is `tiered_v2`, the request is rejected, because a `local` topic cannot be converted to Tiered Storage v2. ### [](#change-the-cleanup-policy)Change the cleanup policy The cleanup policy determines how to clean up the partition log files when they reach a certain size: - `delete` deletes data based on age or log size. Topics retain all records until then. - `compact` compacts the data by only keeping the latest values for each KEY. - `compact,delete` combines both methods. Unlike compacted topics, which keep only the most recent message for a given key, topics configured with a `delete` cleanup policy provide a running history of all changes for those topics. > ⚠️ **WARNING** > > All topic properties take effect immediately after being set. Do not modify properties on internal Redpanda topics (such as `__consumer_offsets`, `_schemas`, or other system topics) as this can cause cluster instability. For example, to change a topic’s policy to `compact`, run: ```bash rpk topic alter-config [TOPICS…] —-set cleanup.policy=compact ``` For details on compaction in Redpanda, see [Compaction settings](https://docs.redpanda.com/streaming/current/manage/cluster-maintenance/compaction-settings/). ### [](#configure-write-caching)Configure write caching Write caching is a relaxed mode of [`acks=all`](https://docs.redpanda.com/streaming/current/develop/produce-data/configure-producers/#acksall) that provides better performance at the expense of durability. It acknowledges a message as soon as it is received and acknowledged on a majority of brokers, without waiting for it to be written to disk. This provides lower latency while still ensuring that a majority of brokers acknowledge the write. Write caching applies to user topics. It does not apply to transactions or consumer offsets: data written in the context of a transaction and consumer offset commits is always written to disk and fsynced before being acknowledged to the client. > 📝 **NOTE** > > For clusters in [development mode](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-redpanda/rpk-redpanda-mode/#development-mode), write caching is enabled by default. For clusters in production mode, it is disabled by default. Only enable write caching on workloads that can tolerate some data loss in the case of multiple, simultaneous broker failures. Leaving write caching disabled safeguards your data against complete data center or availability zone failures. #### [](#configure-at-cluster-level)Configure at cluster level To enable write caching by default in all user topics, set the cluster-level property [`write_caching_default`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#write_caching_default): `rpk cluster config set write_caching_default=true` With `write_caching_default` set to true at the cluster level, Redpanda fsyncs to disk according to [`raft_replica_max_pending_flush_bytes`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#raft_replica_max_pending_flush_bytes) and [`raft_replica_max_flush_delay_ms`](https://docs.redpanda.com/streaming/current/reference/properties/cluster-properties/#raft_replica_max_flush_delay_ms), whichever is reached first. #### [](#configure-at-topic-level)Configure at topic level To override the cluster-level setting at the topic level, set the topic-level property `write.caching`: `rpk topic alter-config my_topic --set write.caching=true` With `write.caching` enabled at the topic level, Redpanda fsyncs to disk according to `flush.ms` and `flush.bytes`, whichever is reached first. ### [](#remove-a-configuration-setting)Remove a configuration setting You can remove a configuration that overrides the default setting, and the setting will use the default value again. For example, suppose you altered the cleanup policy to use `compact` instead of the default, `delete`. Now you want to return the policy setting to the default. To remove the configuration setting `cleanup.policy=compact`, run `rpk topic alter-config` with the `--delete` flag: ```bash rpk topic alter-config [TOPICS...] --delete cleanup.policy ``` ## [](#list-topic-configuration-settings)List topic configuration settings To display all the configuration settings for a topic, run: ```bash rpk topic describe -c ``` The `-c` flag limits the command output to just the topic configurations. This command is useful for checking the default configuration settings before you make any changes and for verifying changes after you make them. The following command output displays after running `rpk topic describe test-topic`, where `test-topic` was created with default settings: ```bash rpk topic describe test_topic SUMMARY ======= NAME test_topic PARTITIONS 1 REPLICAS 1 CONFIGS ======= KEY VALUE SOURCE cleanup.policy delete DYNAMIC_TOPIC_CONFIG compression.type producer DEFAULT_CONFIG max.message.bytes 1048576 DEFAULT_CONFIG message.timestamp.type CreateTime DEFAULT_CONFIG redpanda.datapolicy function_name: script_name: DEFAULT_CONFIG redpanda.remote.delete true DEFAULT_CONFIG redpanda.remote.read false DEFAULT_CONFIG redpanda.remote.write false DEFAULT_CONFIG redpanda.storage.mode unset DEFAULT_CONFIG redpanda.storage.mode.impl unset DEFAULT_CONFIG retention.bytes -1 DEFAULT_CONFIG retention.local.target.bytes -1 DEFAULT_CONFIG retention.local.target.ms 86400000 DEFAULT_CONFIG retention.ms 604800000 DEFAULT_CONFIG segment.bytes 1073741824 DEFAULT_CONFIG ``` Suppose you add two partitions, and increase the number of replicas to 3. The new command output confirms the changes in the `SUMMARY` section: SUMMARY ======= NAME test\_topic PARTITIONS 3 REPLICAS 3 ## [](#delete-a-topic)Delete a topic To delete a topic, run: ```bash rpk topic delete ``` When a topic is deleted, its underlying data is deleted, too. To delete multiple topics at a time, provide a space-separated list. For example, to delete two topics named `topic1` and `topic2`, run: ```bash rpk topic delete topic1 topic2 ``` You can also use the `-r` flag to specify one or more regular expressions; then, any topic names that match the pattern you specify are deleted. For example, to delete topics with names that start with “f” and end with “r”, run: ```bash rpk topic delete -r '^f.*' '.*r$' ``` Note that the first regular expression must start with the `^` symbol, and the last expression must end with the `$` symbol. This requirement helps prevent accidental deletions. ## [](#delete-records-from-a-topic)Delete records from a topic Redpanda allows you to delete data from the beginning of a partition up to a specific offset (a monotonically increasing sequence number for records in a partition). Deleting records frees up disk space, which is especially helpful if your producers are pushing more data than anticipated in your retention plan. Delete records when you know that all consumers have read up to that given offset, and the data is no longer needed. There are different ways to delete records from a topic, including using the [`rpk topic trim-prefix`](https://docs.redpanda.com/streaming/current/reference/rpk/rpk-topic/rpk-topic-trim-prefix/) command, using the `DeleteRecords` Kafka API with Kafka clients, or using Redpanda Console. > 📝 **NOTE** > > - To delete records, `cleanup.policy` must be set to `delete` or `compact,delete`. > > - Object storage is deleted asynchronously. After messages are deleted, the partition’s start offset will have advanced, but garbage collection of deleted segments may not be complete. > > - Similar to Kafka, after deleting records, local storage and object storage may still contain data for deleted offsets. (Redpanda does not truncate segments. Instead, it bumps the start offset, then it attempts to delete as many whole segments as possible.) Data before the new start offset is not visible to clients but could be read by someone with access to the local disk of a Redpanda node. > ⚠️ **WARNING** > > When you delete records from a topic with a timestamp, Redpanda advances the partition start offset to the first record whose timestamp is after the threshold. If record timestamps are not in order with respect to offsets, this may result in unintended deletion of data. Before using a timestamp, verify that timestamps increase in the same order as offsets in the topic to avoid accidental data loss. For example: > > ```bash > rpk topic consume -n 50 --format '%o %d{go[2006-01-02T15:04:05Z07:00]} %k %v' > ``` ## [](#next-steps)Next steps [Configure Producers](https://docs.redpanda.com/streaming/current/develop/produce-data/configure-producers/) ## Suggested labs - [Stream Stock Market Data from a CSV file Using Node.js](https://docs.redpanda.com/labs/clients/stock-market-activity-nodejs/) - [Stream Stock Market Data from a CSV file Using Python](https://docs.redpanda.com/labs/clients/stock-market-activity-python/) - [Build a Chat Room Application with Redpanda and Golang](https://docs.redpanda.com/labs/clients/docker-go/) - [Build a Chat Room Application with Redpanda and Java](https://docs.redpanda.com/labs/clients/docker-java/) - [Build a Chat Room Application with Redpanda and Node.js](https://docs.redpanda.com/labs/clients/docker-nodejs/) - [Build a Chat Room Application with Redpanda and Python](https://docs.redpanda.com/labs/clients/docker-python/) - [Build a Chat Room Application with Redpanda and Rust](https://docs.redpanda.com/labs/clients/docker-rust/) See more [Search all labs](https://docs.redpanda.com/labs)