Concord.Compression (Concord v2.0.0)

Value compression for Concord KV store.

Provides transparent compression for large values to reduce memory usage and improve performance. Compression is automatically applied based on configurable size thresholds.

Configuration

config :concord,
  compression: [
    enabled: true,
    algorithm: :zlib,        # :zlib or :gzip
    threshold_bytes: 1024,   # Compress values larger than 1KB
    level: 6                 # Compression level 0-9 (0=none, 9=max)
  ]

Compression Format

Compressed values are stored as tuples: {:compressed, algorithm, binary} Uncompressed values are stored as-is.

Examples

# Compress a value
compressed = Concord.Compression.compress("large data...")
# {:compressed, :zlib, <<...>>}

# Decompress automatically
value = Concord.Compression.decompress(compressed)
# "large data..."

# Check if value should be compressed
Concord.Compression.should_compress?("small")  # false
Concord.Compression.should_compress?(large_data)  # true

Summary

Types

algorithm()

compressed_value()

Functions

compress(value, opts \\ [])

Compresses a value if it exceeds the configured size threshold.

config()

Returns the compression configuration.

decompress(value)

Decompresses a value if it was compressed.

should_compress?(value, opts \\ [])

Checks if a value should be compressed based on size threshold.

stats(value)

Returns compression statistics for a value.

Types

algorithm()

@type algorithm() :: :zlib | :gzip

compressed_value()

@type compressed_value() :: {:compressed, algorithm(), binary()}

Functions

compress(value, opts \\ [])

@spec compress(
  term(),
  keyword()
) :: term() | compressed_value()

Compresses a value if it exceeds the configured size threshold.

Options

:algorithm - Compression algorithm (:zlib or :gzip)
:level - Compression level 0-9 (default: 6)
:force - Force compression regardless of size (default: false)

Examples

iex> Concord.Compression.compress("small value")
"small value"

iex> large_value = String.duplicate("x", 2048)
iex> Concord.Compression.compress(large_value)
{:compressed, :zlib, <<...>>}

iex> Concord.Compression.compress("force compress", force: true)
{:compressed, :zlib, <<...>>}

config()

@spec config() :: keyword()

Returns the compression configuration.

decompress(value)

@spec decompress(term() | compressed_value()) :: term()

Decompresses a value if it was compressed.

Automatically detects compressed values and decompresses them. Non-compressed values are returned as-is.

Examples

iex> Concord.Compression.decompress("plain value")
"plain value"

iex> compressed = {:compressed, :zlib, binary}
iex> Concord.Compression.decompress(compressed)
"original value"

should_compress?(value, opts \\ [])

@spec should_compress?(
  term(),
  keyword()
) :: boolean()

Checks if a value should be compressed based on size threshold.

Examples

iex> Concord.Compression.should_compress?("small")
false

iex> large = String.duplicate("x", 2048)
iex> Concord.Compression.should_compress?(large)
true

stats(value)

@spec stats(term()) :: map()

Returns compression statistics for a value.

Examples

iex> value = String.duplicate("x", 2048)
iex> Concord.Compression.stats(value)
%{
  original_size: 2048,
  compressed_size: 45,
  compression_ratio: 45.5,
  savings_bytes: 2003,
  savings_percent: 97.8
}