nodetool compact

Forces a major compaction on one or more tables, merging all SSTables into a single SSTable.

Synopsis

nodetool [connection_options] compact [options] [--] [keyspace [table ...]]

See connection options for connection options.

Description

nodetool compact triggers an immediate compaction operation, consolidating SSTables. By default, it performs a major compaction that merges all SSTables for a table into one.

Major Compaction Warning

Major compaction creates a single large SSTable. This can cause:

Significant disk space usage (temporarily doubles space needed)
High I/O impact on production workloads
Long-running operations that cannot be easily stopped
Interference with normal compaction strategies

Use with extreme caution in production.

Arguments

Argument	Description
`keyspace`	Keyspace to compact. If omitted, compacts all keyspaces
`table`	Specific table(s) to compact. If omitted, compacts all tables

Options

Option	Description
`-s, --split-output`	Don't create single SSTable; output multiple based on strategy
`--user-defined`	Treat positional arguments as SSTable `Data.db` file paths and compact only those files
`-st, --start-token`	Start token for compaction range (inclusive)
`-et, --end-token`	End token for compaction range (inclusive)
`--partition`	String representation of a single partition key to compact

Mutually Exclusive Options

The following option combinations are rejected at invocation:

--user-defined with -s/--split-output
--user-defined with -st/-et or --partition
-s/--split-output with -st/-et or --partition

Examples

Compact Specific Table

nodetool compact my_keyspace my_table

Major compaction of single table.

Compact with Split Output

nodetool compact -s my_keyspace my_table

Recommended Over Major Compaction

The -s flag prevents creating one giant SSTable:

Respects compaction strategy's target SSTable sizes
Reduces disk space spike
Better for subsequent compaction operations

Compact Token Range

nodetool compact -st 0 -et 1000000000000 my_keyspace my_table

Compacts only SSTables containing data in the specified token range.

Compact All Tables in Keyspace

nodetool compact my_keyspace

Compact Everything

nodetool compact

Use With Caution

Running nodetool compact without arguments compacts every table on the node. This is rarely appropriate in production and should only be performed during planned maintenance windows with careful monitoring.

When to Use

Legitimate Use Cases

Scenario	Reason
After bulk delete	Remove tombstones (with caution)
Before decommission	Reduce data to stream
Test/dev environments	Simplify SSTable state
Preparing for backup	Consolidate for smaller backup

After Bulk Deletes

If a large amount of data was deleted and tombstones need cleanup:

# First, check tombstone warnings in logs
# Then, if gc_grace_seconds has passed:
nodetool compact -s my_keyspace my_table

Tombstone Considerations

Tombstones older than gc_grace_seconds will be removed
Ensure repair completed before bulk delete compaction
Consider garbagecollect instead for tombstone cleanup

When NOT to Use

Avoid Major Compaction

Do not run major compaction:

As routine maintenance - Let compaction strategies work
On large tables - Can take hours/days
Under production load - Severe I/O impact
When disk space is limited - Requires ~2x table size
On TWCS tables - Destroys time-window boundaries

Compaction Strategies Handle This

Modern compaction strategies (LCS, TWCS, UCS) are designed to maintain optimal SSTable layouts. Manual major compaction often works against these strategies.

Impact Analysis

Disk Space

Before: 10 SSTables × 10 GB = 100 GB
During: Original 100 GB + New merged SSTable (growing to ~100 GB) = ~200 GB peak
After: 1 SSTable × ~95 GB (after compression/tombstone removal)

Disk Space Requirement

Ensure at least 2× the table size in free disk space before major compaction.

I/O Impact

Phase	I/O Pattern
Read	Sequential reads of all SSTables
Write	Sequential write of new SSTable
Duration	Hours for large tables

Effect on Queries

Read latency increases during compaction (more disk I/O)
Write latency generally unaffected
Coordinator operations may timeout more frequently

Monitoring Compaction

Check Progress

nodetool compactionstats

Shows:

Active compactions
Progress percentage
Bytes processed
Estimated completion time

Check History

nodetool compactionhistory

Shows completed compaction operations.

Stop If Necessary

nodetool stop COMPACTION

Stopping Compaction

Stopping a compaction leaves partial results. The incomplete SSTable will be cleaned up, but the operation will need to restart from scratch.

Alternatives to Major Compaction

For Tombstone Cleanup

nodetool garbagecollect my_keyspace my_table

Removes only tombstones without full compaction.

For Regular Maintenance

Let the compaction strategy handle it. Monitor with:

nodetool tablestats my_keyspace.my_table | grep -i "compacted\|sstable"

For Specific SSTables

nodetool compact --user-defined /path/to/nb-1-big-Data.db /path/to/nb-2-big-Data.db ...

Runs a user-defined compaction over only the listed SSTables. Positional arguments are interpreted as SSTable Data.db file paths (not a keyspace/table pair). Multiple files may be listed; they are submitted together as a single compaction task via forceUserDefinedCompaction.

Requirements and constraints:

Paths must point to existing Data.db files on the node where the command is executed
All listed SSTables must belong to the same table
Must not be combined with -s/--split-output, -st/-et, or --partition
The compaction strategy assigned to the table controls how the output SSTable(s) are produced

Typical uses:

Consolidating a specific set of overlapping SSTables identified via sstablemetadata or nodetool tablestats
Forcing tombstone purging on a known-problematic SSTable without a full major compaction
Re-running compaction on SSTables left behind by an interrupted compaction or import

Strategy-Specific Behavior

Size-Tiered (STCS)

Major compaction creates one SSTable, which STCS then treats as a single tier. Subsequent writes create new small SSTables, and the cycle begins again.

Leveled (LCS)

Major compaction places all data in L0, forcing a cascade of compactions to redistribute to proper levels. This is very disruptive.

Time-Window (TWCS)

Never Major Compact TWCS Tables

Major compaction merges time windows together, destroying the time-based organization that TWCS depends on. This severely impacts:

TTL-based expiration
Time-range query efficiency
Future compaction behavior

Unified (UCS)

Similar considerations to LCS; major compaction disrupts the density-based organization.

Best Practices

Compaction Guidelines

Prefer -s flag - Split output respects strategy
Limit scope - Specify keyspace and table
Check disk space - Ensure 2× table size available
Off-peak hours - Run during low traffic
Monitor progress - Use compactionstats
Consider alternatives - garbagecollect for tombstones
Never on TWCS - Destroys time windows

Command	Relationship
compactionstats	Monitor compaction progress
tablestats	Check SSTable counts
flush	Flush memtables before compaction