topic prop update

Author: paulohtb6

modules/reference/partials/properties/topic-properties.adoc

@@ -317,6 +317,8 @@ endif::[]
 
 The retention time for tombstone records in a compacted topic. Redpanda removes tombstone records after the retention limit is exceeded.
 
+This property supports three states: set to a specific millisecond value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (no per-topic limit applied). Setting the value to 0 means tombstone records are immediately eligible for removal.
+
 If you have enabled Tiered Storage and set <<redpandaremoteread,`redpanda.remote.read`>> or <<redpandaremotewrite,`redpanda.remote.write`>> for the topic, you cannot enable tombstone removal.
 
 If both `delete.retention.ms` and the cluster property config_ref:tombstone_retention_ms,true,properties/cluster-properties[] are set, `delete.retention.ms` overrides the cluster level tombstone retention for an individual topic.
@@ -499,6 +501,8 @@ endif::[]
 
 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.
 
+This property supports three states: set to a specific byte value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (transfers all locally retained data).
+
 [cols="1s,2a"]
 |===
 | Property | Value
@@ -546,6 +550,8 @@ endif::[]
 
 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.
 
+This property supports three states: set to a specific millisecond value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (transfers all locally retained data).
+
 [cols="1s,2a"]
 |===
 | Property | Value
@@ -832,6 +838,8 @@ endif::[]
 
 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.
 
+This property supports three states: set to a specific ratio value (including 0.0), unset (inherits cluster default), or disabled by setting to a negative value (inherits cluster default). Setting the value to 0.0 means compaction is always eligible regardless of dirty ratio.
+
 [cols="1s,2a"]
 |===
 | Property | Value
@@ -1701,7 +1709,9 @@ endif::[]
 
 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 xref:cluster-properties.adoc#retention_bytes[`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.
+This property supports three states: set to a specific byte value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (no per-topic limit applied). Setting the value to 0 means partitions are immediately eligible for cleanup.
+
+If `retention.bytes` is set to a non-negative value, it overrides the cluster property xref:cluster-properties.adoc#retention_bytes[`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.
 
@@ -1754,6 +1764,8 @@ endif::[]
 
 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 <<retentionbytes, `retention.bytes`>> without Tiered Storage.
 
+This property supports three states: set to a specific byte value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (no per-topic limit applied). Setting the value to 0 means data in local storage is immediately eligible for cleanup.
+
 [cols="1s,2a"]
 |===
 | Property | Value
@@ -1801,6 +1813,8 @@ endif::[]
 
 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 <<retentionms, `retention.ms`>> without Tiered Storage.
 
+This property supports three states: set to a specific millisecond value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (no per-topic limit applied). Setting the value to 0 means data in local storage is immediately eligible for cleanup.
+
 [cols="1s,2a"]
 |===
 | Property | Value
@@ -1848,9 +1862,11 @@ endif::[]
 // tag::category-retention-compaction[]
 === 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.
+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 `retention.ms` is set to a positive value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`log_retention_ms`] for the topic.
+This property supports three states: set to a specific millisecond value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (no per-topic limit applied). Setting the value to 0 means data is immediately eligible for cleanup.
+
+If `retention.ms` is set to a non-negative value, it overrides the cluster property xref:./cluster-properties.adoc#log_retention_ms[`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.
 
@@ -1956,7 +1972,9 @@ endif::[]
 
 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 xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`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`.
+This property supports three states: set to a specific millisecond value (including 0), unset (inherits cluster default), or disabled by setting to a negative value (inherits cluster default). Setting the value to 0 means segments are immediately eligible for closure.
+
+If set to a non-negative value, `segment.ms` overrides the cluster property xref:./cluster-properties.adoc#log_segment_ms[`log_segment_ms`]. Values are automatically clamped between the cluster bounds set by xref:./cluster-properties.adoc#log_segment_ms_min[`log_segment_ms_min`] (default: 10 minutes) and xref:./cluster-properties.adoc#log_segment_ms_max[`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`.
 
 [cols="1s,2a"]
 |===