This is an automated email from the ASF dual-hosted git repository.
csun5285 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new 4fd5df927ea [doc](compaction) mark single replica compaction as
deprecated in 2.x/3.x docs (#3981)
4fd5df927ea is described below
commit 4fd5df927eab7d62129d28ebefc4457d84aeffc1
Author: Chenyang Sun <[email protected]>
AuthorDate: Tue Jul 14 12:11:47 2026 +0800
[doc](compaction) mark single replica compaction as deprecated in 2.x/3.x
docs (#3981)
Single replica compaction was removed in Doris 4.1.2
(apache/doris#63771) because its peer selection carries a data
correctness risk: replicas pull compacted files based on periodically
refreshed replica info while each replica advances through versions
independently, so the selection can act on a stale view of the cluster
and cause subtle data inconsistencies.
Add deprecation notices to the compaction feature docs and the
enable_single_replica_compaction property descriptions in CREATE-TABLE
for versions 2.1 and 3.x, in both English and Chinese.
## Versions
- [ ] dev
- [ ] 4.x
- [x] 3.x
- [x] 2.1 or older (not covered by version/language sync gate)
---
.../version-2.1/admin-manual/trouble-shooting/compaction.md | 4 ++++
.../sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md | 2 +-
.../version-3.x/admin-manual/trouble-shooting/compaction.md | 4 ++++
.../sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md | 2 +-
.../version-2.1/admin-manual/trouble-shooting/compaction.md | 4 ++++
.../sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md | 2 +-
.../version-3.x/admin-manual/trouble-shooting/compaction.md | 4 ++++
.../sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md | 2 +-
8 files changed, 20 insertions(+), 4 deletions(-)
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/trouble-shooting/compaction.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/trouble-shooting/compaction.md
index aa658ffe66d..96418e7a0a5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/trouble-shooting/compaction.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/admin-manual/trouble-shooting/compaction.md
@@ -68,6 +68,10 @@ Segment compaction 有以下特点：
## 单副本 compaction
+:::caution 已废弃
+单副本 compaction 功能已废弃，并自 Doris 4.1.2 版本起移除。原因是其对端副本的选择存在数据正确性风险：拉取 compaction
结果的副本需要基于周期性刷新的副本信息来选择拉取的对象和版本，而各副本的版本推进又相互独立，这一选择可能基于过期的集群状态做出，从而引发难以察觉的数据不一致。不建议开启该功能。`enable_single_replica_compaction`
属性在 Doris 4.x 中已被删除。
+:::
+
默认情况下，多个副本的 compaction 是独立进行的，每个副本在都需要消耗 CPU 和 IO 资源。开启单副本 compaction
后，在一个副本进行 compaction 后，其他几个副本拉取 compaction 后的文件，因此 CPU 资源只需要消耗 1 次，节省了 N - 1 倍
CPU 消耗（N 是副本数）。
单副本 compaction 在表的 PROPERTIES 中通过参数 `enable_single_replica_compaction` 指定，默认为
false 不开启，设置为 true 开启。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
index 7da9e14ea0d..9f8d6ed2ca8 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
@@ -354,7 +354,7 @@ rollup 可以创建的同步物化视图功能有限。已不再推荐使用。
| enable_unique_key_merge_on_write | Unique 表是否使用 Merge-on-Write
实现。该属性在 2.1 版本之前默认关闭，从 2.1 版本开始默认开启。 |
| light_schema_change | 是否使用 Light Schema Change
优化。如果设置成 `true`, 对于值列的加减操作，可以更快地，同步地完成。该功能在 2.0.0 及之后版本默认开启。 |
| disable_auto_compaction | 是否对这个表禁用自动
Compaction。如果这个属性设置成 `true`, 后台的自动 Compaction 进程会跳过这个表的所有 Tablet。 |
-| enable_single_replica_compaction | 是否对这个表开启单副本
Compaction。如果这个属性设置成 `true`, 这个表的 Tablet 的所有副本只有一个进行实际的 compaction
动作，其他副本的从该副本拉取完成 compaction 的 rowset。 |
+| enable_single_replica_compaction |
**已废弃**。该功能因对端副本选择存在数据正确性风险，已自 Doris 4.1.2 版本起移除，不建议开启。是否对这个表开启单副本
Compaction。如果这个属性设置成 `true`, 这个表的 Tablet 的所有副本只有一个进行实际的 compaction
动作，其他副本的从该副本拉取完成 compaction 的 rowset。 |
| enable_duplicate_without_keys_by_default | 当配置为`true`时，如果创建表的时候没有指定
Unique、Aggregate 或 Duplicate 时，会默认创建一个没有排序列和前缀索引的 Duplicate 模型的表。 |
| skip_write_index_on_load | 是否对这个表开启数据导入时不写索引。如果这个属性设置成
`true`, 数据导入的时候不写索引（目前仅对倒排索引生效），而是在 Compaction 的时候延迟写索引。这样可以避免首次写入和 Compaction
重复写索引的 CPU 和 IO 资源消耗，提升高吞吐导入的性能。 |
| compaction_policy | 配置这个表的 Compaction
的合并策略，仅支持配置为 time_series 或者 size_basedtime_series: 当 rowset
的磁盘体积积攒到一定大小时进行版本合并。合并后的 rowset 直接晋升到 base compaction 阶段。在时序场景持续导入的情况下有效降低
compact 的写入放大率。此策略将使用 time_series_compaction 为前缀的参数调整 Compaction 的执行 |
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/compaction.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/compaction.md
index aa658ffe66d..96418e7a0a5 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/compaction.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/compaction.md
@@ -68,6 +68,10 @@ Segment compaction 有以下特点：
## 单副本 compaction
+:::caution 已废弃
+单副本 compaction 功能已废弃，并自 Doris 4.1.2 版本起移除。原因是其对端副本的选择存在数据正确性风险：拉取 compaction
结果的副本需要基于周期性刷新的副本信息来选择拉取的对象和版本，而各副本的版本推进又相互独立，这一选择可能基于过期的集群状态做出，从而引发难以察觉的数据不一致。不建议开启该功能。`enable_single_replica_compaction`
属性在 Doris 4.x 中已被删除。
+:::
+
默认情况下，多个副本的 compaction 是独立进行的，每个副本在都需要消耗 CPU 和 IO 资源。开启单副本 compaction
后，在一个副本进行 compaction 后，其他几个副本拉取 compaction 后的文件，因此 CPU 资源只需要消耗 1 次，节省了 N - 1 倍
CPU 消耗（N 是副本数）。
单副本 compaction 在表的 PROPERTIES 中通过参数 `enable_single_replica_compaction` 指定，默认为
false 不开启，设置为 true 开启。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
index dbd87142532..dc9cf6d825d 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
@@ -358,7 +358,7 @@ rollup 可以创建的同步物化视图功能有限。已不再推荐使用。
| enable_unique_key_merge_on_write | Unique 表是否使用 Merge-on-Write
实现。该属性在 2.1 版本之前默认关闭，从 2.1 版本开始默认开启。 |
| light_schema_change | 是否使用 Light Schema Change
优化。如果设置成 `true`, 对于值列的加减操作，可以更快地，同步地完成。该功能在 2.0.0 及之后版本默认开启。 |
| disable_auto_compaction | 是否对这个表禁用自动
Compaction。如果这个属性设置成 `true`, 后台的自动 Compaction 进程会跳过这个表的所有 Tablet。 |
-| enable_single_replica_compaction | 是否对这个表开启单副本
Compaction。如果这个属性设置成 `true`, 这个表的 Tablet 的所有副本只有一个进行实际的 compaction
动作，其他副本的从该副本拉取完成 compaction 的 rowset。 |
+| enable_single_replica_compaction |
**已废弃**。该功能因对端副本选择存在数据正确性风险，已自 Doris 4.1.2 版本起移除，不建议开启。是否对这个表开启单副本
Compaction。如果这个属性设置成 `true`, 这个表的 Tablet 的所有副本只有一个进行实际的 compaction
动作，其他副本的从该副本拉取完成 compaction 的 rowset。 |
| enable_duplicate_without_keys_by_default | 当配置为`true`时，如果创建表的时候没有指定
Unique、Aggregate 或 Duplicate 时，会默认创建一个没有排序列和前缀索引的 Duplicate 模型的表。 |
| skip_write_index_on_load | 是否对这个表开启数据导入时不写索引。如果这个属性设置成
`true`, 数据导入的时候不写索引（目前仅对倒排索引生效），而是在 Compaction 的时候延迟写索引。这样可以避免首次写入和 Compaction
重复写索引的 CPU 和 IO 资源消耗，提升高吞吐导入的性能。 |
| compaction_policy | 配置这个表的 Compaction
的合并策略，仅支持配置为 time_series 或者 size_basedtime_series: 当 rowset
的磁盘体积积攒到一定大小时进行版本合并。合并后的 rowset 直接晋升到 base compaction 阶段。在时序场景持续导入的情况下有效降低
compact 的写入放大率。此策略将使用 time_series_compaction 为前缀的参数调整 Compaction 的执行 |
diff --git
a/versioned_docs/version-2.1/admin-manual/trouble-shooting/compaction.md
b/versioned_docs/version-2.1/admin-manual/trouble-shooting/compaction.md
index 25ef51f46bb..2547f4e59f9 100644
--- a/versioned_docs/version-2.1/admin-manual/trouble-shooting/compaction.md
+++ b/versioned_docs/version-2.1/admin-manual/trouble-shooting/compaction.md
@@ -53,6 +53,10 @@ Refer to this
[link](https://github.com/apache/doris/pull/12866) for more inform
## Single replica compaction
+:::caution Deprecated
+Single replica compaction has been deprecated and is removed since Doris
4.1.2, because its peer selection carries a data correctness risk: the replicas
that pull the compacted files choose which peer and version to fetch from based
on replica information that is only refreshed periodically, while each replica
advances through versions independently. This selection can therefore act on a
stale view of the cluster and lead to subtle data inconsistencies. Enabling
this feature is not recom [...]
+:::
+
By default, compaction for multiple replicas is performed independently, with
each replica consuming CPU and IO resources. When single replica compaction is
enabled, only one replica performs the compaction. Afterward, the other
replicas pull the compacted files from this replica, resulting in CPU resources
being consumed only once, saving N - 1 times CPU usage (where N is the number
of replicas).
Single replica compaction is specified in the table's PROPERTIES via the
parameter `enable_single_replica_compaction`, which is false by default
(disabled). To enable it, set the parameter to true.
diff --git
a/versioned_docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
b/versioned_docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
index 2a5485611dd..1824050426b 100644
---
a/versioned_docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
+++
b/versioned_docs/version-2.1/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
@@ -353,7 +353,7 @@ The functionality of creating synchronized materialized
views with rollup is lim
| enable_unique_key_merge_on_write | Whether the Unique table uses the
Merge-on-Write implementation. This property was default disabled before
version 2.1 and default enabled from version 2.1 onwards. |
| light_schema_change | Whether to use the Light Schema Change optimization.
If set to `true`, addition and subtraction operations on value columns can be
completed faster and synchronously. This feature is enabled by default in
versions 2.0.0 and later. |
| disable_auto_compaction | Whether to disable automatic compaction for this
table. If this property is set to `true`, the background automatic compaction
process will skip all tablets of this table. |
-| enable_single_replica_compaction | Whether to enable single-replica
compaction for this table. If this property is set to `true`, only one replica
of all replicas of the table's tablets will perform the actual compaction
action, and other replicas will pull the compacted rowset from that replica. |
+| enable_single_replica_compaction | **Deprecated.** This feature has been
removed since Doris 4.1.2 due to a data correctness risk in its peer selection,
and enabling it is not recommended. Whether to enable single-replica compaction
for this table. If this property is set to `true`, only one replica of all
replicas of the table's tablets will perform the actual compaction action, and
other replicas will pull the compacted rowset from that replica. |
| enable_duplicate_without_keys_by_default | When set to `true`, if no Unique,
Aggregate, or Duplicate is specified when creating a table, a Duplicate model
table without sort columns and prefix indexes will be created by default. |
| skip_write_index_on_load | Whether to enable not writing indexes during data
import for this table. If this property is set to `true`, indexes will not be
written during data import (currently only effective for inverted indexes), but
will be delayed until compaction. This can avoid the CPU and IO resource
consumption of writing indexes repeatedly during the first write and
compaction, improving the performance of high-throughput imports. |
| compaction_policy | Configures the compaction merge policy for this table,
supporting only time_series or size_basedtime_series: When the disk volume of
rowsets accumulates to a certain size, version merging is performed. The merged
rowset is directly promoted to the base compaction phase. This effectively
reduces the write amplification of compact in scenarios with continuous
imports. This policy will use parameters prefixed with time_series_compaction
to adjust the execution of compa [...]
diff --git
a/versioned_docs/version-3.x/admin-manual/trouble-shooting/compaction.md
b/versioned_docs/version-3.x/admin-manual/trouble-shooting/compaction.md
index 25ef51f46bb..2547f4e59f9 100644
--- a/versioned_docs/version-3.x/admin-manual/trouble-shooting/compaction.md
+++ b/versioned_docs/version-3.x/admin-manual/trouble-shooting/compaction.md
@@ -53,6 +53,10 @@ Refer to this
[link](https://github.com/apache/doris/pull/12866) for more inform
## Single replica compaction
+:::caution Deprecated
+Single replica compaction has been deprecated and is removed since Doris
4.1.2, because its peer selection carries a data correctness risk: the replicas
that pull the compacted files choose which peer and version to fetch from based
on replica information that is only refreshed periodically, while each replica
advances through versions independently. This selection can therefore act on a
stale view of the cluster and lead to subtle data inconsistencies. Enabling
this feature is not recom [...]
+:::
+
By default, compaction for multiple replicas is performed independently, with
each replica consuming CPU and IO resources. When single replica compaction is
enabled, only one replica performs the compaction. Afterward, the other
replicas pull the compacted files from this replica, resulting in CPU resources
being consumed only once, saving N - 1 times CPU usage (where N is the number
of replicas).
Single replica compaction is specified in the table's PROPERTIES via the
parameter `enable_single_replica_compaction`, which is false by default
(disabled). To enable it, set the parameter to true.
diff --git
a/versioned_docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
b/versioned_docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
index 6ece9fb516e..465b89bae57 100644
---
a/versioned_docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
+++
b/versioned_docs/version-3.x/sql-manual/sql-statements/table-and-view/table/CREATE-TABLE.md
@@ -357,7 +357,7 @@ The functionality of creating synchronized materialized
views with rollup is lim
| enable_unique_key_merge_on_write | Whether the Unique table uses the
Merge-on-Write implementation. This property was default disabled before
version 2.1 and default enabled from version 2.1 onwards. |
| light_schema_change | Whether to use the Light Schema Change optimization.
If set to `true`, addition and subtraction operations on value columns can be
completed faster and synchronously. This feature is enabled by default in
versions 2.0.0 and later. |
| disable_auto_compaction | Whether to disable automatic compaction for this
table. If this property is set to `true`, the background automatic compaction
process will skip all tablets of this table. |
-| enable_single_replica_compaction | Whether to enable single-replica
compaction for this table. If this property is set to `true`, only one replica
of all replicas of the table's tablets will perform the actual compaction
action, and other replicas will pull the compacted rowset from that replica. |
+| enable_single_replica_compaction | **Deprecated.** This feature has been
removed since Doris 4.1.2 due to a data correctness risk in its peer selection,
and enabling it is not recommended. Whether to enable single-replica compaction
for this table. If this property is set to `true`, only one replica of all
replicas of the table's tablets will perform the actual compaction action, and
other replicas will pull the compacted rowset from that replica. |
| enable_duplicate_without_keys_by_default | When set to `true`, if no Unique,
Aggregate, or Duplicate is specified when creating a table, a Duplicate model
table without sort columns and prefix indexes will be created by default. |
| skip_write_index_on_load | Whether to enable not writing indexes during data
import for this table. If this property is set to `true`, indexes will not be
written during data import (currently only effective for inverted indexes), but
will be delayed until compaction. This can avoid the CPU and IO resource
consumption of writing indexes repeatedly during the first write and
compaction, improving the performance of high-throughput imports. |
| compaction_policy | Configures the compaction merge policy for this table,
supporting only time_series or size_basedtime_series: When the disk volume of
rowsets accumulates to a certain size, version merging is performed. The merged
rowset is directly promoted to the base compaction phase. This effectively
reduces the write amplification of compact in scenarios with continuous
imports. This policy will use parameters prefixed with time_series_compaction
to adjust the execution of compa [...]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
