Compression Advisor¶

Prerequisites¶

• Python 3.

• The ScyllaDB Python driver (scylla-driver), used to read the current compression configuration over CQL. Install it with:

  pip install scylla-driver
  

  Without the driver, the tool still runs and prints the heatmap and recommendations, but cannot compare against the current configuration.

• Network access from where you run the tool to:

  • the ScyllaDB CQL native transport port (9042 by default), and

  • the ScyllaDB Admin REST API port (10000 by default).

• The SSTABLE_COMPRESSION_DICTS cluster feature must be enabled on all nodes. If not enabled, the estimate_compression_ratios REST API is unavailable and Compression Advisor reports that the API returned invalid JSON.

Usage¶

python3 tools/compression_advisor.py --host <node-ip> --keyspace <ks> --table <tbl> [options]

For example:

python3 tools/compression_advisor.py --host 127.0.0.1 --keyspace myks --table mytbl

To disable the ANSI color output (for example when redirecting to a file):

python3 tools/compression_advisor.py --host 127.0.0.1 --keyspace myks --table mytbl --no-color

If the cluster uses PasswordAuthenticator, pass CQL credentials so the tool can read the current compression configuration:

python3 tools/compression_advisor.py --host 127.0.0.1 --keyspace myks --table mytbl --username scylla --password mypassword

Options¶

Run the tool with -h / --help for the full list of options.

Output¶

The advisor prints three sections:

• Heatmap grid — the estimated compression ratio for every candidate compressor / chunk length / level combination, color-coded so the most effective configurations stand out. The current configuration is highlighted.

• Summary table — the current configuration alongside the best LZ4 and best ZSTD candidates, with the estimated size reduction relative to the current setting.

• Recommended change — a single ALTER TABLE statement for the best overall recommendation (chosen between the best LZ4 and best ZSTD candidate). When a dictionary-aware compressor with a retrained dictionary is recommended, the tool also prints the corresponding retrain_dict REST call needed to train the compression dictionary.

The recommended ALTER TABLE statement always quotes the keyspace and table identifiers, uses the dictionary-capable compressor names returned by the estimator (for example ZstdWithDictsCompressor), and includes compression_level for ZSTD. For example:

ALTER TABLE "myks"."mytbl" WITH compression = {'sstable_compression': 'ZstdWithDictsCompressor', 'chunk_length_in_kb': '4', 'compression_level': '5'};

If the recommendation uses a retrained dictionary, the tool also prints, as comments, the REST call to train it:

-- Then retrain the dictionary (requires SSTABLE_COMPRESSION_DICTS feature):
-- POST /storage_service/retrain_dict?keyspace=myks&cf=mytbl

When no change improves the estimated ratio by more than 5%, the tool reports that the current configuration is already optimal instead of printing an ALTER TABLE statement.