Docs Self-Managed Reference Properties Topic Configuration Properties Topic Configuration Properties A topic-level property sets a Redpanda or Kafka configuration for a particular topic. Many topic-level properties have corresponding cluster properties that set a default value for all topics of a cluster. To customize the value for a topic, you can set a topic-level property that overrides the value of the corresponding cluster property. For information on how to configure topic properties, see Configure Topic Properties. 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. Topic property mappings Topic property Corresponding cluster property cleanup.policy log_cleanup_policy compaction.strategy compaction_strategy compression.type log_compression_type delete.retention.ms tombstone_retention_ms flush.bytes flush_bytes flush.ms flush_ms initial.retention.local.target.bytes initial_retention_local_target_bytes initial.retention.local.target.ms initial_retention_local_target_ms max.compaction.lag.ms max_compaction_lag_ms max.message.bytes kafka_batch_max_bytes message.timestamp.type log_message_timestamp_type min.cleanable.dirty.ratio min_cleanable_dirty_ratio min.compaction.lag.ms min_compaction_lag_ms replication.factor default_topic_replications retention.bytes retention_bytes retention.local.target.bytes retention_local_target_bytes retention.local.target.ms retention_local_target_ms retention.ms log_retention_ms segment.bytes log_segment_size segment.ms log_segment_ms write.caching write_caching_default Retention and Compaction Properties These properties control how data is stored, for how long, and when it is deleted or compacted. cleanup.policy The cleanup policy to apply for log segments of a topic. When cleanup.policy is set, it overrides the cluster property log_cleanup_policy for the topic. Type: string Accepted values: [delete, compact, compact,delete] Default: delete Values: delete - Deletes data according to size-based or time-based retention limits, or both. compact - Deletes data according to a key-based retention policy, discarding all but the latest value for each key. compact,delete - The latest values are kept for each key, while the remaining data is deleted according to retention limits. Related cluster property: log_cleanup_policy Related topics: Configure segment size Compacted topics in Tiered Storage compaction.strategy Specifies the strategy used to determine which records to remove during log compaction. The compaction strategy controls how Redpanda identifies and removes duplicate records while preserving the latest value for each key. Type: string Default: offset Accepted values: offset - Uses record offsets to determine which records to compact (default and currently the only supported strategy) Related cluster property: compaction_strategy delete.retention.ms The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded. If you have enabled Tiered Storage and set redpanda.remote.read or redpanda.remote.write for the topic, you cannot enable tombstone removal. If both delete.retention.ms and the cluster property tombstone_retention_ms are set, delete.retention.ms overrides the cluster level tombstone retention for an individual topic. Type: integer Unit: milliseconds Accepted values: [1, 9223372036854775] Default: null Related cluster property: tombstone_retention_ms Related topics: Tombstone record removal max.compaction.lag.ms The maximum amount of time (in ms) that a log segment can remain unaltered before it is eligible for compaction in a compact topic. Overrides the cluster property max_compaction_lag_ms for the topic. Type: integer Unit: milliseconds Accepted values: [1, 9223372036854775] Default: 9223372036854775 Related cluster property: max_compaction_lag_ms Related topics: Configure maximum compaction lag min.cleanable.dirty.ratio The minimum ratio between the number of bytes in dirty segments and the total number of bytes in closed segments that must be reached before a partition’s log is eligible for compaction in a compact topic. Type: number Accepted values: [0, 1.0] Default: null Related cluster property: min_cleanable_dirty_ratio Related topics: Compaction Settings min.compaction.lag.ms The minimum amount of time (in ms) that a log segment must remain unaltered before it can be compacted in a compact topic. Overrides the cluster property min_compaction_lag_ms for the topic. Type: integer Unit: milliseconds Accepted values: [0, 9223372036854775] Default: 0 Related cluster property: min_compaction_lag_ms Related topics: Configure minimum compaction lag retention.bytes A size-based retention limit that configures the maximum size that a topic partition can grow before becoming eligible for cleanup. If retention.bytes is set to a positive value, it overrides the cluster property retention_bytes for the topic, and the total retained size for the topic is retention.bytes multiplied by the number of partitions for the topic. When both size-based (retention.bytes) and time-based (retention.ms) retention limits are set, cleanup occurs when either limit is reached. Type: integer Unit: bytes Accepted values: [1, 9223372036854775807] Default: null Related cluster property: retention_bytes Related topics: Configure message retention retention.ms A time-based retention limit that configures the maximum duration that a log’s segment file for a topic is retained before it becomes eligible to be cleaned up. To consume all data, a consumer of the topic must read from a segment before its retention.ms elapses, otherwise the segment may be compacted and/or deleted. If a non-positive value, no per-topic limit is applied. If retention.ms is set to a positive value, it overrides the cluster property log_retention_ms for the topic. When both size-based (retention.bytes) and time-based (retention.ms) retention limits are set, the earliest occurring limit applies. Type: integer Unit: milliseconds Accepted values: [-9223372036854775808, 9223372036854775807] Default: null Related cluster property: log_retention_ms Related topics: Configure message retention Segment and Message Properties These properties control the size and lifecycle of log segment files and settings for individual messages. compression.type Redpanda ignores this property and always uses producer compression semantics. If producers send compressed data, Redpanda stores and serves it as-is. If producers send uncompressed data, Redpanda stores it uncompressed. This property exists for Apache Kafka compatibility. Configure compression in your producers instead of using this topic property. Compression reduces message size and improves throughput, but increases CPU utilization. Enable producer batching to increase compression efficiency. When set, this property overrides the cluster property log_compression_type for the topic. Type: string Accepted values: producer. The following values are accepted for Kafka compatibility but ignored: gzip, snappy, lz4, zstd, none. Default: producer Related cluster property: log_compression_type Related topics: Message batching Common producer configuration options max.message.bytes The maximum size of a message or batch of a topic. If a compression type is enabled, max.message.bytes sets the maximum size of the compressed message or batch. If max.message.bytes is set to a positive value, it overrides the cluster property kafka_batch_max_bytes for the topic. Type: integer Unit: bytes Accepted values: [1, 2147483647] Default: null Related cluster property: kafka_batch_max_bytes Related topics: Message batching message.timestamp.type The source of a message’s timestamp: either the message’s creation time or its log append time. When message.timestamp.type is set, it overrides the cluster property log_message_timestamp_type for the topic. Type: string Accepted values: [CreateTime, LogAppendTime] Default: CreateTime Values: CreateTime LogAppendTime Related cluster property: log_message_timestamp_type segment.bytes The maximum size of an active log segment for a topic. When the size of an active segment exceeds segment.bytes, the segment is closed and a new active segment is created. The closed, inactive segment is then eligible to be cleaned up according to retention properties. When segment.bytes is set to a positive value, it overrides the cluster property log_segment_size for the topic. Type: integer Unit: bytes Accepted values: [1, 9223372036854775807] Default: null Related cluster property: log_segment_size Related topics: Configure segment size Configure message retention Remote Read Replicas segment.ms The maximum duration that a log segment of a topic is active (open for writes and not deletable). A periodic event, with segment.ms as its period, forcibly closes the active segment and transitions, or rolls, to a new active segment. The closed (inactive) segment is then eligible to be cleaned up according to cleanup and retention properties. If set to a positive duration, segment.ms overrides the cluster property log_segment_ms. Values are automatically clamped between the cluster bounds set by log_segment_ms_min (default: 10 minutes) and log_segment_ms_max (default: 1 year). If your configured value exceeds these bounds, Redpanda uses the bound value and logs a warning. Check current cluster bounds with rpk cluster config get log_segment_ms_min log_segment_ms_max. Type: integer Unit: milliseconds Accepted values: [600000, 31536000000] Default: null Related cluster property: log_segment_ms Related topics: Log rolling Performance and Cluster Properties These properties control disk flushing, replication, and how topics interact with the cluster. flush.bytes The maximum bytes not fsynced per partition. If this configured threshold is reached, the log is automatically fsynced, even though it wasn’t explicitly requested. Type: integer Unit: bytes Accepted values: [1, 9223372036854775807] Default: 262144 Related cluster property: flush_bytes Related topics: Configure Producers flush.ms The maximum delay (in ms) between two subsequent fsyncs. After this delay, the log is automatically fsynced. Type: integer Unit: milliseconds Accepted values: [1, 9223372036854775] Default: 100 Related cluster property: flush_ms Related topics: Configure Producers redpanda.leaders.preference The preferred location (rack) for partition leaders of a topic. This property inherits the value from the default_leaders_preference cluster configuration property. You may override the cluster-wide setting by specifying the value for individual topics. If the cluster configuration property enable_rack_awareness is set to false, Leader Pinning is disabled across the cluster. Type: string Default: none Values: none: Opt out the topic from Leader Pinning. racks:<rack1>[,<rack2>,…]: Specify the preferred location (rack) of all topic partition leaders. The list can contain one or more rack IDs. If you specify multiple IDs, Redpanda tries to distribute the partition leader locations equally across brokers in these racks. Related topics: Leader pinning replication.factor The number of replicas of a topic to save in different nodes (brokers) of a cluster. If replication.factor is set to a positive value, it overrides the cluster property default_topic_replication for the topic. Although replication.factor isn’t returned or displayed by rpk topic describe as a valid Kafka property, you can set it using rpk topic alter-config. When the replication.factor of a topic is altered, it isn’t simply a property value that’s updated, but rather the actual replica sets of topic partitions that are changed. Type: integer Accepted values: [1, 512] Default: null Related cluster property: default_topic_replication Related topics: Choose the replication factor Change the replication factor write.caching The write caching mode to apply to a topic. When write.caching is set, it overrides the cluster property write_caching_default. Write caching 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. With acks=all, this provides lower latency while still ensuring that a majority of brokers acknowledge the write. Fsyncs follow flush.ms and flush.bytes, whichever is reached first. Type: boolean Default: false Values: true - Enables write caching for a topic, according to flush.ms and flush.bytes. false - Disables write caching for a topic, according to flush.ms and flush.bytes. Related cluster property: write_caching_default Related topics: Write caching Tiered Storage properties Configure properties to manage topics for Tiered Storage. initial.retention.local.target.bytes A size-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If null (default), all locally retained data is transferred. Type: integer Unit: bytes Accepted values: [1, 9223372036854775807] Default: null Related cluster property: initial_retention_local_target_bytes Related topics: Fast commission and decommission through Tiered Storage initial.retention.local.target.ms A time-based initial retention limit for Tiered Storage that determines how much data in local storage is transferred to a partition replica when a cluster is resized. If null (default), all locally retained data is transferred. Type: integer Unit: milliseconds Accepted values: [1, 9223372036854775] Default: null Related cluster property: initial_retention_local_target_ms Related topics: Fast commission and decommission through Tiered Storage redpanda.remote.delete A flag that enables deletion of data from object storage for Tiered Storage when it’s deleted from local storage for a topic. redpanda.remote.delete doesn’t apply to Remote Read Replica topics: a Remote Read Replica topic isn’t deleted from object storage when this flag is true. Type: boolean Default: false for topics created using Redpanda 22.2 or earlier. true for topics created in Redpanda 22.3 and later, including new topics on upgraded clusters. Related topics: Tiered Storage redpanda.remote.read A flag for enabling Redpanda to fetch data for a topic from object storage to local storage. When set to true together with redpanda.remote.write, it enables the Tiered Storage feature. Type: boolean Default: false Related topics: Tiered Storage redpanda.remote.recovery A flag that enables the recovery or reproduction of a topic from object storage for Tiered Storage. The recovered data is saved in local storage, and the maximum amount of recovered data is determined by the local storage retention limits of the topic. You can only configure redpanda.remote.recovery when you create a topic. You cannot apply this setting to existing topics. Type: boolean Default: false Related topics: Tiered Storage redpanda.remote.write A flag for enabling Redpanda to upload data for a topic from local storage to object storage. When set to true together with redpanda.remote.read, it enables the Tiered Storage feature. Type: boolean Default: false Related topics: Tiered Storage retention.local.target.bytes A size-based retention limit for Tiered Storage that configures the maximum size that a topic partition in local storage can grow before becoming eligible for cleanup. It applies per partition and is equivalent to retention.bytes without Tiered Storage. Type: integer Unit: bytes Accepted values: [1, 9223372036854775807] Default: null Related cluster property: retention_local_target_bytes Related topics: Tiered Storage retention.local.target.ms A time-based retention limit for Tiered Storage that sets the maximum duration that a log’s segment file for a topic is retained in local storage before it’s eligible for cleanup. This property is equivalent to retention.ms without Tiered Storage. Type: integer Unit: milliseconds Accepted values: [1, 9223372036854775] Default: 86400000 Related cluster property: retention_local_target_ms Related topics: Tiered Storage Remote Read Replica properties Configure properties to manage topics for Remote Read Replicas. redpanda.remote.readreplica The name of the object storage bucket for a Remote Read Replica topic. Setting redpanda.remote.readreplica together with either redpanda.remote.read or redpanda.remote.write results in an error. Type: string Default: null Related topics: Remote Read Replicas Apache Iceberg integration properties Integrate Redpanda topics as Iceberg tables. redpanda.iceberg.delete Whether the corresponding Iceberg table is deleted upon deleting the topic. Type: boolean Default: true Related topics: About Iceberg Topics redpanda.iceberg.invalid.record.action Whether to write invalid records to a dead-letter queue (DLQ). Type: string Default: dlq_table Values: drop: Disable the DLQ and drop invalid records. dlq_table: Write invalid records to a separate DLQ Iceberg table. Related topics: Troubleshoot errors redpanda.iceberg.mode Enable the Iceberg integration for the topic. You can choose one of four modes. Type: string Default: disabled Values: key_value: Creates an Iceberg table with a Key column and a Value column. Redpanda stores the raw topic content in the Value column. value_schema_id_prefix: Creates an Iceberg table whose structure matches the Redpanda schema for the topic, with columns corresponding to each field. Redpanda uses the Schema Registry wire format, consisting of the "magic byte" and schema ID encoded in the payload header, to parse the topic values per field and store them in the corresponding table columns. value_schema_latest: Creates an Iceberg table whose structure matches the latest schema version in Schema Registry that matches the subject name. This mode is compatible with Avro and Protobuf schemas and is used when you don’t produce to the topic using the wire format. See Choose an Iceberg Mode for details on using this mode. disabled: Disables writing to an Iceberg table for the topic. Related topics: Specify Iceberg Schema About Iceberg Topics redpanda.iceberg.partition.spec The partitioning specification for the Iceberg table. Type: string Default: (hour(redpanda.timestamp)) Related topics: Use custom partitioning redpanda.iceberg.target.lag.ms Controls how often the data in the Iceberg table is refreshed with new data from the topic. Redpanda attempts to commit all data produced to the topic within the lag target, subject to resource availability. Type: integer Default: 60000 Related topics: About Iceberg Topics Back to top × Simple online edits For simple changes, such as fixing a typo, you can edit the content directly on GitHub. Edit on GitHub Or, open an issue to let us know about something that you want us to change. Open an issue Contribution guide For extensive content updates, or if you prefer to work locally, read our contribution guide . Was this helpful? thumb_up thumb_down group Ask in the community mail Share your feedback group_add Make a contribution 🎉 Thanks for your feedback! Object Storage Properties Release Notes