Configure compaction

To keep the database healthy, the database periodically merges and rewrites SSTables while discarding old data through a process called compaction. This process combines existing SSTables by merging keys, combining columns, evicting tombstones, reconciling writes against the same row, and rebuilding the index in a new, consolidated SSTable.

DSE provides a start-up option to test compaction strategies without affecting your production workloads.

Choose a compaction strategy

It is important that you choose an appropriate compaction strategy for your use case and data model. Misconfigured or unsuitable compaction strategies can degrade performance and overconsume system resources. The following table summarizes the supported compaction strategies and general configuration guidance for each strategy.

Supported compaction strategies
Strategy	Use case	Configuration notes	General disk requirements
SizeTieredCompactionStrategy (STCS)	Good for write-heavy workloads that prioritize fast writes over read latency.	In most cases, the default properties are sufficient. If this strategy produces too many outliers, or compaction runs more often that you would like, then the size range and thresholds might need tuning.	Make sure there is sufficient memory and storage available for the number and size of SSTables as well as overhead for the compaction process. The sum of all SSTables being compacted must be smaller than the remaining disk space, ideally less than 50 percent. Avoid exceeding 50 percent of free disk space, which is likely to occur with manual compaction where all SSTables are merged into one giant SSTable.
LeveledCompactionStrategy (LCS)	Good for read-heavy workloads that perform best with fewer SSTables.	Understand the mechanisms and resource requirements at L0 compared to L1 and higher. Requires tuning `memtable` parameters for optimal performance, such as less frequent flushing of memtables to avoid overloading L0.	Due to guaranteed non-overlapping row key ranges, LCS requires much less disk space for compaction compared to STCS. However, you must account for the use of STCS as a failsafe at L0, which requires more disk space. Furthermore, the maximum overhead for LCS increases dramatically beyond L3 because each level is approximately 10 times larger than the preceding level. I/O saturation is possible when compacting at the highest levels due to progressively larger SSTables at each additional level. For more information, see LCS compaction write amplification and disk requirements.
TimeWindowCompactionStrategy (TWCS)	Designed for time series data and expiring time-to-live (TTL) workloads, especially data that is written once, in chronological order, and never updated.	TWCS must be enabled when you create a table. You cannot apply TWCS retroactively to existing tables that weren’t created with the proper time windowing layout.	Similar to STCS, TWCS requires a maximum disk space overhead of 50 percent of the total size of SSTables in the last created bucket. To ensure adequate disk space, determine the size of the largest bucket or window ever generated, and divide that value by 2: `TWCS disk space = Largest bucket size / 2`. For new deployments, you must monitor and tune this during cluster performance tests.

If you aren’t sure which strategy to use, see Compaction strategy questionnaire.

Configure compaction in `cassandra.yaml`

Compaction is configured primarily at the table-level, including the compaction strategy and options to tune each compaction strategy.

Additionally, there are higher-level settings that can impact compaction performance, particularly for large partitions that require more control over memory use and disk I/O. The compaction parameters in cassandra.yaml configure global compaction behaviors for an entire node, such as compaction_throughput_mb_per_sec and concurrent_compactors. These parameter’s aren’t a replacement for table-level compaction properties.

Additionally, memtable parameters in cassandra.yaml influence compaction performance because they determine how frequently memtable flushes happen.

To tune memtable flushes, use the memtable parameters in cassandra.yaml.

Don’t set the memtable_flush_period_in_ms table property. There are few cases where an explicit memtable flush cadence is preferable to the database’s automatic flush triggers. DataStax recommends leaving this property at the default value, which is 0 (disabled).

Configure compaction with `CREATE TABLE` and `ALTER TABLE`

When you create or alter a table, you can set compaction properties. The compaction strategy is set in the compaction.class property. Additional compaction.* properties are determined by the strategy (class), and there are several properties that are available to all strategies. All compaction properties are optional, and all have reasonable default values that provide adequate performance for most use cases, including class. For example:

Create a table and set the compaction strategy to LCS:

CREATE TABLE users (
  id UUID PRIMARY KEY,
  name text,
  email text
) WITH compaction = { 'class' : 'LeveledCompactionStrategy' };

Alter a table to use STCS and set the min_threshold property:

ALTER TABLE users
  WITH compaction =
  {'class' : 'SizeTieredCompactionStrategy', 'min_threshold' : 6 }

Although it isn’t necessary to tune every compaction property, it is important that you understand which properties are most relevant to your chosen strategy and whether you need to tune certain properties based on your workloads.

If a node’s compaction performance is unacceptable, consider tuning global compaction parameters in cassandra.yaml before tuning individual tables.

The following sections describe notable compaction properties for each strategy and specific use cases. This isn’t a comprehensive reference of all possible compaction properties or values. For more information about compaction properties and syntax, see the CQL documentation for CREATE TABLE and ALTER TABLE.

When you alter a table’s compaction properties, the changes apply to new SSTables only. To rewrite existing SSTables with the new configuration, run the following:

nodetool upgradesstables -a KEYSPACE_NAME TABLE_NAME

Properties for the `SizeTieredCompactionStrategy` class

STCS selects SSTables for compaction based on their size, grouping SSTables of similar size into buckets and compacting them together into a new, larger SSTable.

bucket_low and bucket_high

The size range is based on the dynamically calculated average size of all SSTables for a given table with margins set by the bucket_low and bucket_high properties. The values of these properties are multipliers that determine the lower and upper bounds of the size range relative to the average SSTable size. The entire range is calculated as follows:

lower bound = average SSTable size in KB x bucket_low
upper bound = average SSTable size in KB x bucket_high

range in KB = [lower bound, upper bound]

By default, bucket_low is 0.5 and bucket_high is 1.5. This creates a margin of 50 percent on either side of the average: SSTables are selected for compaction if they are anywhere from 0.5 times the average up to 1.5 times the average. For most workloads, the default is acceptable.

min_threshold

The minimum number of SSTables required to trigger compaction is set by the min_threshold property. The default is 4 SSTables.

To increase the probability for compaction, decrease min_threshold or adjust the bucket_* properties to expand the size range. However, be aware that more frequent compactions inherently impact performance through disk I/O.

max_threshold

STCS naturally produces outliers that never or rarely fall within the size range. It is also possible to create a temporary stalemate scenario where there aren’t enough matching SSTables to satisfy min_threshold. To avoid accumulating too many SSTables overall, the database forcefully runs compaction when the number of SSTables reaches the max_threshold. The default is 32 SSTables. However, frequent max_threshold compactions can indicate that STCS isn’t compacting frequently enough.

min_sstable_size

Workloads that flush memtables to very small SSTables (less than 50 MB) can cause STCS to cycle through excessive compactions of these small SSTables before producing SSTables of any notable size. To avoid these excessive compaction cycles, all SSTables smaller than min_sstable_size are grouped into a single bucket for compaction. The default is 50 MB.

Before tuning min_sstable_size, DataStax recommends reducing max_threshold to 25 or 15. If your workloads hit the reduced threshold frequently, then tune min_sstable_size or other parameters.

Properties for the `LeveledCompactionStrategy` class

LCS organizes SSTables into levels, where each level has a target size and SSTables are compacted to maintain this structure. This strategy helps to limit read amplification and maintain predictable performance for read-heavy workloads.

sstable_size_in_mb: Sets the target SSTable size for leveling. SSTables at L1 and higher are merged into SSTables with a size greater than or equal to sstable_size_in_mb. The default is 160 MB.
memtable tuning for L0: Because L0 receives all newly flushed SSTables, it isn’t predictably sized like higher levels. To prevent too many small SSTables from flooding L0, make sure all memtable parameters in cassandra.yaml are tuned appropriately for your workloads. With LCS, DataStax recommends less frequent memtable flushes compared to tables that use STCS.

Properties for the `TimeWindowCompactionStrategy` class

TWCS compacts SSTables by chronological time windows where only one window is active (receiving new memtable flushes) at a time. When a window closes, all of the window’s SSTables are compacted into one final SSTable for that window.

The ideal configuration for TWCS is extremely use-case specific.

compaction_window_unit and compaction_window_size

Configure time window intervals:

compaction_window_unit: A Java TimeUnit specifying the unit of measurement for time windows, such as seconds, hours, or days.
compaction_window_size: An integer specifying the number of units per window.

The default is 1 day (compaction_window_unit: 'days' and compaction_window_size: 1)

DataStax recommends planning your time window configuration so that there are fewer than 50 (ideally, 30) inactive (closed) time windows. To calculate this, divide your TTL period by the target number of inactive windows. For example, if your TTL period is 365 days with 30 inactive windows, 365 divided by 30 is approximately 12 days per window. Therefore, your time window configuration would be compaction_window_unit: 'days' and compaction_window_size: 12.

STCS properties for active window compactions

TWCS uses STCS for minor compactions in the active time window. This prevents the active window from accumulating an excessive number of SSTables before the final compaction when the window closes. As a result, you can use all STCS properties with the TimeWindowCompactionStrategy class to configure the active window’s compaction behavior.

For TWCS, DataStax recommends setting max_threshold to no more than 20.

unsafe_aggressive_sstable_expiration

Whether to drop expired SSTables without checking if their data shadows other SSTables.

Enabling this property can cause data consistency and integrity issues, such as resurrected deletes (zombies).

This property can only be enabled if allow_unsafe_aggressive_sstable_expiration is true in cassandra.yaml.

For more information about appropriate use cases for this property, see CASSANDRA-13418 and DB-902.

Default: false

Tune single-SSTable tombstone compactions

To avoid accumulation of tombstones in SSTables that haven’t been selected for compaction by a table’s compaction strategy, the database can compact individual SSTables specifically to clean up tombstones. These tombstone compactions are in addition to compactions triggered by the table’s compaction strategy.

Before tuning tombstone compaction properties, be aware that tombstone compactions consume system resources like any other compaction event.

The following compaction properties determine the frequency of single-SSTable tombstone compactions:

tombstone_threshold: Sets the maximum acceptable ratio of tombstones to all columns. Single-SSTable tombstone compactions are triggered when an SSTable’s estimated tombstone ratio is higher than tombstone_threshold.
tombstone_compaction_interval: Sets the minimum SSTable age in seconds to be eligible for tombstone compaction. This applies to all SSTables (memtable flushes, compactions triggered by the compaction strategy, and previous tombstone compactions). The default is 86400 seconds (24 hours).

To evict tombstones faster, reduce tombstone_compaction_interval. If this value is too low, some SSTables might be continuously compacted.
unchecked_tombstone_compaction: To disregard an SSTable’s age before triggering single-SSTable tombstone compaction, set unchecked_tombstone_compaction to true.

Monitor compaction

You can monitor the performance impact of compaction configuration changes using compaction metrics and logs.

DSE provides a start-up option to test compaction strategies without affecting your production workloads.

Check pending compactions

Too many pending compactions often indicates a compaction tuning issue.

To retrieve pending compactions, use your preferred monitoring solution or one of the following commands:

nodetool sjk mx -f Value -mg -b org.apache.cassandra.metrics:type=Compaction,name=PendingTasks

nodetool compactionstats

Compaction metrics

The following compaction metrics attributes are exposed through CompactionManagerMBean:

Compaction metrics
Attribute	Description
`BytesCompacted`	Total number of bytes compacted since server start or restart.
`CompletedTasks`	Number of completed compactions since server start or restart.
`PendingTasks`	Estimated number of compactions remaining to perform.
`TotalCompactionsCompleted`	Total number of compactions since server start or restart.

For more information, see Monitor DataStax Enterprise (DSE) clusters.

Extended logging

Extended compaction logging applies to the entire cluster. Enabling extended compaction logs on any table enables extended logging for all tables on all nodes in the entire cluster.

To enable extended logging for compaction, set log_all to true in the table’s compaction properties.

Extended compaction logs are stored in a separate file. For more information, see Read extended compaction logging.

Configure compaction

Choose a compaction strategy

Configure compaction in `cassandra.yaml`

Configure compaction with `CREATE TABLE` and `ALTER TABLE`

Properties for the `SizeTieredCompactionStrategy` class

Properties for the `LeveledCompactionStrategy` class

Properties for the `TimeWindowCompactionStrategy` class

Tune single-SSTable tombstone compactions

Monitor compaction

Check pending compactions

Compaction metrics

Extended logging

See also

Was this helpful?

Give Feedback