Skip to main content
By default, ClickHouse applies lz4 compression in the self-managed version, and zstd in ClickHouse Cloud. For MergeTree-engine family you can change the default compression method in the compression section of a server configuration. You can also define the compression method for each individual column in the CREATE TABLE query.
The Default codec can be specified to reference default compression which may depend on different settings (and properties of data) in runtime. Example: value UInt64 CODEC(Default) — the same as lack of codec specification. See also Adaptive Codec Selection. Also you can remove current CODEC from the column and use default compression from config.xml:
Codecs can be combined in a pipeline, for example, CODEC(Delta, Default).
You can’t decompress ClickHouse database files with external utilities like lz4. Instead, use the special clickhouse-compressor utility.
Compression is supported for the following table engines:
  • MergeTree family. Supports column compression codecs and selecting the default compression method by compression settings.
  • Log family. Uses the lz4 compression method by default and supports column compression codecs.
  • Set. Only supported the default compression.
  • Join. Only supported the default compression.
ClickHouse supports general purpose codecs and specialized codecs.

General Purpose Codecs

NONE

NONE — No compression.

LZ4

LZ4 — Lossless data compression algorithm used by default. Applies LZ4 fast compression.

LZ4HC

LZ4HC[(level)] — LZ4 HC (high compression) algorithm with configurable level. Default level: 9. Setting level <= 0 applies the default level. Possible levels: [1, 12]. Recommended level range: [4, 9].

ZSTD

ZSTD[(level)]ZSTD compression algorithm with configurable level. Possible levels: [1, 22]. Default level: 1. High compression levels are useful for asymmetric scenarios, like compress once, decompress repeatedly. Higher levels mean better compression and higher CPU usage.

ZXC

ZXC[(level)] — asymmetric zxc compression algorithm with configurable level. Possible levels: [1, 7]. Default level: 3. ZXC trades slow compression for very fast decompression, at a compression ratio between LZ4 and ZSTD. It is a good fit for the compress-once, decompress-many pattern, and decompresses fastest on modern ARM cores. Higher levels mean better compression and slower compression, while decompression stays fast.
This codec is experimental and requires SET allow_experimental_codecs = 1 to use.

Obsolete: ZSTD_QAT

Obsolete: DEFLATE_QPL

Specialized Codecs

These codecs are designed to make compression more effective by exploiting specific features of the data. Some of these codecs do not compress data themselves, they instead preprocess the data such that a second compression stage using a general-purpose codec can achieve a higher data compression rate.

Delta

Delta(delta_bytes) — Compression approach in which raw values are replaced by the difference of two neighboring values, except for the first value that stays unchanged. delta_bytes is the maximum size of raw values, the default value is sizeof(type). Specifying delta_bytes as an argument is deprecated and support will be removed in a future release. Delta is a data preparation codec, i.e. it cannot be used stand-alone.

DoubleDelta

DoubleDelta(bytes_size) — Calculates delta of deltas and writes it in compact binary form. The bytes_size has a similar meaning than delta_bytes in Delta codec. Specifying bytes_size as an argument is deprecated and support will be removed in a future release. Optimal compression rates are achieved for monotonic sequences with a constant stride, such as time series data. Can be used with any numeric type. Implements the algorithm used in Gorilla TSDB, extending it to support 64-bit types. Uses 1 extra bit for 32-bit deltas: 5-bit prefixes instead of 4-bit prefixes. For additional information, see Compressing Time Stamps in Gorilla: A Fast, Scalable, In-Memory Time Series Database. DoubleDelta is a data preparation codec, i.e. it cannot be used stand-alone.

GCD

GCD() - - Calculates the greatest common denominator (GCD) of the values in the column, then divides each value by the GCD. Can be used with integer, decimal and date/time columns. The codec is well suited for columns with values that change (increase or decrease) in multiples of the GCD, e.g. 24, 28, 16, 24, 8, 24 (GCD = 4). GCD is a data preparation codec, i.e. it cannot be used stand-alone.

Gorilla

Gorilla(bytes_size) — Calculates XOR between current and previous floating point value and writes it in compact binary form. The smaller the difference between consecutive values is, i.e. the slower the values of the series changes, the better the compression rate. Implements the algorithm used in Gorilla TSDB, extending it to support 64-bit types. Possible bytes_size values: 1, 2, 4, 8, the default value is sizeof(type) if equal to 1, 2, 4, or 8. In all other cases, it’s 1. For additional information, see section 4.1 in Gorilla: A Fast, Scalable, In-Memory Time Series Database.

ALP

ALP(variant) — Adaptive lossless compression for floating-point data. Supports Float32 and Float64. For details, see ALP: Adaptive lossless floating-point compression. The codec accepts an optional variant argument:
  • ALP() or ALP(AUTO) (default) — Uses STD and falls back to RD based on the estimated compressed size.
  • ALP(STD) — Standard ALP variant. Represents each value as an exact scaled integer using decimal powers, then compresses the resulting integers with Frame-of-Reference and bit-packing. Non-representable values are stored as raw exceptions. Works best for numbers originating from decimals (e.g., measurements, prices).
  • ALP(RD) — Real Doubles variant. Reinterprets each value’s bit pattern and splits it into a high part (sign + exponent + top mantissa bits) and a low part. High parts are dictionary-encoded (up to 8 entries), low parts are bit-packed. Works best when many values share the same high bits.
This codec is experimental and requires SET allow_experimental_codecs = 1 to use.

FPC

FPC(level, float_size) - Repeatedly predicts the next floating point value in the sequence using the better of two predictors, then XORs the actual with the predicted value, and leading-zero compresses the result. Similar to Gorilla, this is efficient when storing a series of floating point values that change slowly. For 64-bit values (double), FPC is faster than Gorilla, for 32-bit values your mileage may vary. Possible level values: 1-28, the default value is 12. Possible float_size values: 4, 8, the default value is sizeof(type) if type is Float. In all other cases, it’s 4. For a detailed description of the algorithm see High Throughput Compression of Double-Precision Floating-Point Data.

SZ3

SZ3 or SZ3(algorithm, error_bound_mode, error_bound) - A lossy but error-bound codec (SZ3 Lossy Compressor) for columns of type Float32, Float64, Array(Float32), or Array(Float64). For array columns, compression is most effective when all arrays have the same length (they are then compressed as fixed-width vectors); arrays of different lengths are still supported and are compressed as a flat sequence of values. The codec is not applicable to Map columns, because its keys would be corrupted by lossy compression. Supported values for ‘algorithm’ are ALGO_LORENZO_REG, ALGO_INTERP_LORENZO and ALGO_INTERP. Supported values for ‘error_bound_mode’ are ABS, REL, PSNR and ABS_AND_REL. Argument ‘error_bound’ is the maximum error and of type Float64.
This codec is experimental and requires SET allow_experimental_codecs = 1 to use.

T64

T64 — Compression approach that crops unused high bits of values in integer data types (including Enum, Date and DateTime). At each step of its algorithm, codec takes a block of 64 values, puts them into 64x64 bit matrix, transposes it, crops the unused bits of values and returns the rest as a sequence. Unused bits are the bits, that do not differ between maximum and minimum values in the whole data part for which the compression is used. DoubleDelta and Gorilla codecs are used in Gorilla TSDB as the components of its compressing algorithm. Gorilla approach is effective in scenarios when there is a sequence of slowly changing values with their timestamps. Timestamps are effectively compressed by the DoubleDelta codec, and values are effectively compressed by the Gorilla codec. For example, to get an effectively stored table, you can create it in the following configuration:

Quantized

Quantized(method, dimensions[, ...]) — A specialized codec to support approximate vector search on columns of type Array(Float32), Array(Float64) or Array(BFloat16). It stores the original, full-precision vectors, as well as a compact quantized code per vector alongside. On MergeTree-family tables, vector search queries with setting vector_search_use_quantized_codes will scan the quantized codes to build a shortlist and subsequently rescore the results against the full-precision vectors. This two-stage search reads fewer bytes than a normal full-precision scan at the cost of lower recall. dimensions is the vector length; supported method values are rabitq, turboquant, int8, prefix and product, each a different size / accuracy / distance-function trade-off. The codec can only be set in CREATE TABLE, it cannot be added, removed, or changed through ALTER TABLE, including with ADD COLUMN ... CODEC(Quantized(...)). It cannot be chained with any other codec (not even an encryption codec such as AES_128_GCM_SIV). For more details, see Vector search with quantized codecs.

Encryption Codecs

These codecs don’t actually compress data, but instead encrypt data on disk. These are only available when an encryption key is specified by encryption settings. Note that encryption only makes sense at the end of codec pipelines, because encrypted data usually can’t be compressed in any meaningful way. Encryption codecs:

AES_128_GCM_SIV

CODEC('AES-128-GCM-SIV') — Encrypts data with AES-128 in RFC 8452 GCM-SIV mode.

AES-256-GCM-SIV

CODEC('AES-256-GCM-SIV') — Encrypts data with AES-256 in GCM-SIV mode. These codecs use a fixed nonce and encryption is therefore deterministic. This makes it compatible with deduplicating engines such as ReplicatedMergeTree but has a weakness: when the same data block is encrypted twice, the resulting ciphertext will be exactly the same so an adversary who can read the disk can see this equivalence (although only the equivalence, without getting its content).
Most engines including the “*MergeTree” family create index files on disk without applying codecs. This means plaintext will appear on disk if an encrypted column is indexed.
If you perform a SELECT query mentioning a specific value in an encrypted column (such as in its WHERE clause), the value may appear in system.query_log. You may want to disable the logging.
Example
If compression needs to be applied, it must be explicitly specified. Otherwise, only encryption will be applied to data.
Example

Adaptive Codec Selection

The specialized codecs above can shrink the right data dramatically, but choosing them takes expertise, and no single choice fits a column whose data changes over time. With the MergeTree setting allow_experimental_adaptive_codec_selection enabled, ClickHouse chooses for you. For columns that use the default codec (CODEC(Default) or no CODEC at all), each block is written with whichever codec would compress it smallest, chosen among the table’s default codec, NONE, and specialized codecs suited to the column type. A block is never larger than the default codec would make it, and incompressible data is stored raw (compressing it would produce a slightly larger file that is slower to read). The work happens in the background, on merges and mutations, where the data is recompressed anyway. Insert speed is unaffected. Queries often get faster: less data is fetched from disk, every block a query reads must be decompressed first, and specialized codecs decompress faster than the default LZ4. Each block records the codec it was written with, so reading requires no setting, and the feature can be switched off at any time with all data remaining readable.
You can observe how it works with the mergeTreeCodecBlockCounts table function. Here time grows steadily, so T64, which stores only the bits that vary within a block, beat the default codec on every block. user_id holds hashes that no codec can shrink, so its blocks were stored raw:
Selection currently covers integer-like columns: integers, enums, dates and times, Decimal32/Decimal64, and IPv4.
Last modified on August 5, 2026