This is an automated email from the ASF dual-hosted git repository.
asf-gitbox-commits pushed a commit to branch cassandra-5.0
in repository https://gitbox.apache.org/repos/asf/cassandra.git
The following commit(s) were added to refs/heads/cassandra-5.0 by this push:
new 18f253e0f5 Improve incremental repair documentation clarity
18f253e0f5 is described below
commit 18f253e0f5a1dc2c25f1348330b23124db444326
Author: Doyeon Kim <[email protected]>
AuthorDate: Wed Sep 2 06:57:48 2026 -0500
Improve incremental repair documentation clarity
Patch by Doyeon Kim, reviewed by brads and brandonwilliams for
CASSANDRA-21331
---
.../pages/managing/operating/auto_repair.adoc | 19 ++++++++++++++++---
.../pages/managing/operating/compaction/overview.adoc | 1 +
2 files changed, 17 insertions(+), 3 deletions(-)
diff --git a/doc/modules/cassandra/pages/managing/operating/auto_repair.adoc
b/doc/modules/cassandra/pages/managing/operating/auto_repair.adoc
index 7971263b50..756e875622 100644
--- a/doc/modules/cassandra/pages/managing/operating/auto_repair.adoc
+++ b/doc/modules/cassandra/pages/managing/operating/auto_repair.adoc
@@ -77,10 +77,18 @@ a smaller set of data, so a shorter `min_repair_interval`
such as `1h` is recomm
One should be careful when enabling incremental repair on a cluster for the
first time. While
xref:#repair-token-range-splitter[RepairTokenRangeSplitter] includes a default
configuration to attempt to gracefully
migrate to incremental repair over time, failure to take proper precaution
could overwhelm the cluster with
-xref:managing/operating/compaction/overview.adoc#types-of-compaction[anticompactions].
+xref:managing/operating/compaction/overview.adoc#anticompaction[anticompactions].
+
+This happens because incremental repair must keep repaired and unrepaired data
in separate SSTables. From the
+operator's perspective, a repair runs against a whole table, but Cassandra
executes it as sessions over portions of
+the token space. A participating SSTable typically contains both data covered
by the repair session and data left
+untouched, so Cassandra cannot simply mark the whole SSTable as repaired.
Instead it uses
+xref:managing/operating/compaction/overview.adoc#anticompaction[anticompaction]
to rewrite each participating SSTable,
+separating data covered by the repair session from data that remains
unrepaired. On clusters with large SSTables or
+high partition overlap, rewriting these files can generate substantial disk
I/O and overhead.
No matter how one goes about enabling and running incremental repair, it is
recommended to run a cycle of full repairs
-for the entire cluster as pre-flight step to running incremental repair. This
will put the cluster into a more
+for the entire cluster as a pre-flight step to running incremental repair.
This will put the cluster into a more
consistent state which will reduce the amount of streaming between replicas
when incremental repair initially runs.
If you do not have strong data consistency requirements, one may consider using
@@ -93,13 +101,18 @@ If you do have strong data consistency requirements, then
one must treat all dat
incremental repair against it. Consult
xref:#incremental-repair-defaults[RepairTokenRangeSplitter's Incremental
repair defaults].
+The first incremental repair on an existing cluster still has to compare and
repair the entire unrepaired data set, so
+it acts identically to a full repair in scope. The difference is what happens
afterward: a full repair does not update
+the incremental repair state, while an incremental repair records the repaired
ranges so that later incremental
+repairs evaluate only newly written SSTable files.
+
In particular one should be mindful of the
xref:managing/operating/compaction/overview.adoc[compaction strategy]
you use for your tables and how it might impact incremental repair before
running incremental repair for the first
time:
- *Large SSTables*: When using
xref:managing/operating/compaction/stcs.adoc[SizeTieredCompactionStrategy] or
any
compaction strategy which can create large SSTables including many
partitions the amount of
-
xref:managing/operating/compaction/overview.adoc#types-of-compaction[anticompaction]
that might be required could be
+
xref:managing/operating/compaction/overview.adoc#anticompaction[anticompaction]
that might be required could be
excessive. Using a small `bytes_per_assignment` might contribute to repeated
anticompactions over the same
unrepaired data.
- *Partitions overlapping many SSTables*: If partitions overlap between many
SSTables, the amount of SSTables included
diff --git
a/doc/modules/cassandra/pages/managing/operating/compaction/overview.adoc
b/doc/modules/cassandra/pages/managing/operating/compaction/overview.adoc
index 6a396106b8..fbfe2e83cf 100644
--- a/doc/modules/cassandra/pages/managing/operating/compaction/overview.adoc
+++ b/doc/modules/cassandra/pages/managing/operating/compaction/overview.adoc
@@ -67,6 +67,7 @@ Compaction executes to remove any ranges that a node no
longer owns.
This type of compaction is typically triggered on neighbouring nodes after a
node has been bootstrapped, since the bootstrapping node will take ownership of
some ranges from those nodes.
Secondary index rebuild::
A compaction is triggered if the secondary indexes are rebuilt on a node.
+[[anticompaction]]
Anticompaction::
After repair, the ranges that were actually repaired are split out of the
SSTables that existed when repair started. This type of compaction rewrites
SSTables to accomplish this task.
Sub range compaction::
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
