Advanced Compression Parameters

Fine-tune compression with advanced parameters for optimal performance and ratio

Zstandard provides extensive control over compression behavior through advanced parameters. These allow you to optimize for specific use cases, hardware constraints, or performance requirements.

Setting Parameters

Use ZSTD_CCtx_setParameter() to configure compression parameters:

ZSTD_CCtx* cctx = ZSTD_createCCtx();

// Set compression level
ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, 5);

// Set window size
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 20);

// Set compression strategy
ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_btopt);

// Compress using these parameters
ZSTD_compress2(cctx, dst, dstSize, src, srcSize);

Parameters persist across compression operations until reset or changed.

Compression Level

The compression level is the primary control for the compression ratio vs. speed tradeoff.

// ZSTD_c_compressionLevel
ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, level);

• Range: Negative values to 22
• Default: 3 (ZSTD_CLEVEL_DEFAULT)
• Special: 0 means “use default”

Fast compression (level 1)

ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, 1);
// Fast but lower ratio

Setting the compression level automatically adjusts other parameters dynamically. Manually set parameters “stick” and override level-based defaults.

Window Size

The window size controls the maximum back-reference distance for finding matches.

// ZSTD_c_windowLog (power of 2)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 20);  // 1 MB window

• Power of 2: windowLog=20 means window size = 2^20 = 1 MB
• Range: ZSTD_WINDOWLOG_MIN to ZSTD_WINDOWLOG_MAX
• Default: 0 (automatic based on source size)
• Impact: Larger windows improve compression but use more memory

// Examples
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 17);  // 128 KB
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 20);  // 1 MB
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 23);  // 8 MB
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 27);  // 128 MB

Larger window sizes require more memory during decompression. Windows >= 128 MB require explicit acknowledgment at decompression time.

Compression Strategies

Strategies control the algorithm used to find matches.

// ZSTD_c_strategy
ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_btopt);

Available strategies (in order of complexity):

typedef enum {
    ZSTD_fast=1,      // Fastest
    ZSTD_dfast=2,     // Fast with better ratio
    ZSTD_greedy=3,    // Greedy matching
    ZSTD_lazy=4,      // Lazy matching
    ZSTD_lazy2=5,     // Lazy matching with more effort
    ZSTD_btlazy2=6,   // Binary tree lazy
    ZSTD_btopt=7,     // Binary tree optimal (level 16+)
    ZSTD_btultra=8,   // Binary tree ultra
    ZSTD_btultra2=9   // Binary tree ultra 2 (strongest)
} ZSTD_strategy;

1. Fast strategies (fast, dfast)

   Best for speed-critical applications:

   ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_fast);
   

   • Minimal CPU usage
   • Lower compression ratios
   • Good for real-time compression
2. Lazy strategies (greedy, lazy, lazy2)

   Balanced performance:

   ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_lazy);
   

   • Moderate CPU usage
   • Good compression ratios
   • Default for mid-range levels
3. Binary tree strategies (btopt, btultra, btultra2)

   Maximum compression:

   ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_btultra2);
   

   • High CPU usage
   • Best compression ratios
   • Used automatically at level 16+

Hash and Chain Tables

These parameters control internal data structures for match finding.

Hash Log

// ZSTD_c_hashLog (power of 2)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_hashLog, 18);

• Size: Hash table size = 2^hashLog entries
• Memory: (1 << (hashLog+2)) bytes
• Impact: Larger tables improve ratio for fast/dfast strategies
• Range: ZSTD_HASHLOG_MIN to ZSTD_HASHLOG_MAX

Chain Log

// ZSTD_c_chainLog (power of 2)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_chainLog, 17);

• Size: Chain table size = 2^chainLog entries
• Memory: (1 << (chainLog+2)) bytes
• Impact: Larger tables improve ratio but slow compression
• Note: Useless for “fast” strategy, useful for “dfast” as secondary probe table

Search Log

// ZSTD_c_searchLog (power of 2)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_searchLog, 7);

• Attempts: Number of search attempts = 2^searchLog
• Impact: More attempts = better ratio, slower compression
• Note: Useless for “fast” and “dfast” strategies

Match Parameters

Minimum Match Length

// ZSTD_c_minMatch
ZSTD_CCtx_setParameter(cctx, ZSTD_c_minMatch, 4);

• Range: ZSTD_MINMATCH_MIN (3) to ZSTD_MINMATCH_MAX (7)
• Default: Depends on strategy (typically 4-6)
• Impact: Larger values increase speed but may decrease ratio

Target Length

// ZSTD_c_targetLength
ZSTD_CCtx_setParameter(cctx, ZSTD_c_targetLength, 128);

Behavior depends on strategy:

• btopt/btultra/btultra2: Length considered “good enough” to stop search
  • Larger values = stronger/slower compression
• fast: Distance between match sampling
  • Larger values = faster/weaker compression

Long Distance Matching (LDM)

LDM improves compression for large files with repeated patterns far apart.

// Enable long distance matching
ZSTD_CCtx_setParameter(cctx, ZSTD_c_enableLongDistanceMatching, 1);

// LDM hash log (default: windowLog - 7)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmHashLog, 20);

// LDM minimum match size (default: 64)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmMinMatch, 64);

// LDM bucket size log (default: 3)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmBucketSizeLog, 3);

// LDM hash rate log
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmHashRateLog, 0);  // Auto

Automatic LDM

// Enabled automatically for:
// - windowLog >= 128 MB
// - strategy >= ZSTD_btopt (level 16+)

LDM increases memory usage and is most effective for files with repetitive content at large distances.

Frame Parameters

Content Size Flag

// Write content size to frame header (default: 1)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_contentSizeFlag, 1);

When enabled, the decompressed size is written to the frame header (when known).

Checksum Flag

// Add 32-bit checksum at end of frame (default: 0)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_checksumFlag, 1);

Enables data integrity verification at decompression.

Dictionary ID Flag

// Write dictionary ID to frame header (default: 1)
ZSTD_CCtx_setParameter(cctx, ZSTD_c_dictIDFlag, 1);

Writes the dictionary ID when using dictionary compression.

Example: Custom Configuration

Here’s an example of fine-tuning compression for a specific use case:

// Configure for maximum ratio on large text files
ZSTD_CCtx* cctx = ZSTD_createCCtx();

// Base compression level
ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, 19);

// Large window for better back-references
ZSTD_CCtx_setParameter(cctx, ZSTD_c_windowLog, 27);  // 128 MB

// Use optimal parsing strategy
ZSTD_CCtx_setParameter(cctx, ZSTD_c_strategy, ZSTD_btultra2);

// Enable long distance matching
ZSTD_CCtx_setParameter(cctx, ZSTD_c_enableLongDistanceMatching, 1);
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmHashLog, 20);
ZSTD_CCtx_setParameter(cctx, ZSTD_c_ldmMinMatch, 128);

// Add checksum for integrity
ZSTD_CCtx_setParameter(cctx, ZSTD_c_checksumFlag, 1);

// Compress
size_t result = ZSTD_compress2(cctx, dst, dstSize, src, srcSize);
CHECK_ZSTD(result);

ZSTD_freeCCtx(cctx);

Parameter Persistence

Parameters remain active until explicitly changed or reset:

// Set parameters
ZSTD_CCtx_setParameter(cctx, ZSTD_c_compressionLevel, 10);
ZSTD_CCtx_setParameter(cctx, ZSTD_c_checksumFlag, 1);

// First compression uses level 10 + checksum
ZSTD_compress2(cctx, dst1, dstSize1, src1, srcSize1);

// Second compression still uses level 10 + checksum
ZSTD_compress2(cctx, dst2, dstSize2, src2, srcSize2);

// Reset to defaults
ZSTD_CCtx_reset(cctx, ZSTD_reset_parameters);

// Now uses default parameters
ZSTD_compress2(cctx, dst3, dstSize3, src3, srcSize3);

Querying Parameters

Get information about supported parameter ranges:

// Get minimum/maximum compression levels
int minLevel = ZSTD_minCLevel();  // Minimum (typically negative)
int maxLevel = ZSTD_maxCLevel();  // Maximum (typically 22)
int defaultLevel = ZSTD_defaultCLevel();  // Default (3)

printf("Compression levels: %d to %d (default: %d)\n", 
       minLevel, maxLevel, defaultLevel);