Crate chronix_encoding 

chronix-encoding

Column-oriented encoding and compression for the Chronix time-series database.

This crate provides type-specific encoders that exploit the statistical properties of time-series data to achieve high compression ratios:

Column type	Encoder	Typical ratio
Timestamps	PcoEncoder — mode recovery + delta + binned ANS	2.7–1092×
Timestamps	DeltaOfDeltaEncoder — delta-of-delta + bit-packing	0.9–63×
Floats	AlpEncoder — decimal reconstruction + FOR bit-packing	4–20×
Floats	ChimpEncoder / GorillaEncoder — XOR-based	1.3–4×
Integers	IntegerEncoder — delta + ZigZag + bit-packing	4–16×
Integers	ForEncoder — Frame-of-Reference (narrow range)	4–32×
Decimals	DecimalEncoder — i128 mantissa over the integer stack	4–1000×
Strings	DictionaryEncoder — string table + index	4–64×
Booleans	BitmapEncoder — 1 bit per value	8×
Any	PlainEncoder — uncompressed fallback	1×

Unified API

ColumnEncoder / ColumnDecoder auto-select the best encoding per column type and transparently fall back to plain when a specialized encoder cannot achieve sufficient compression.

Adaptive Selection

AdaptiveSelector samples values at write time and classifies the data distribution (Constant, SlowlyVarying, Periodic, Random) to pick the optimal encoder. The choice is stored in column metadata for the decoder.

Design Principles

1. Lossless — every encoder guarantees bitwise-exact roundtrip.
2. Zero-copy — decoders operate on byte slices where possible.
3. Auto-selection — the unified API picks the best encoder per column.
4. Fallback — plain encoding is used when compression is not beneficial.

Re-exports

pub use adaptive::AdaptiveSelector;

pub use adaptive::FloatPattern;

pub use adaptive::IntegerPattern;

pub use adaptive::StringPattern;

pub use alp::AlpDecoder;

pub use alp::AlpEncoder;

pub use bitmap::BitmapDecoder;

pub use bitmap::BitmapEncoder;

pub use chimp::Chimp128Decoder;

pub use chimp::Chimp128Encoder;

pub use chimp::ChimpDecoder;

pub use chimp::ChimpEncoder;

pub use decimal::DecimalDecoder;

pub use decimal::DecimalEncoder;

pub use delta::DeltaOfDeltaDecoder;

pub use delta::DeltaOfDeltaEncoder;

pub use dictionary::DictionaryDecoder;

pub use dictionary::DictionaryEncoder;

pub use error::EncodingError;

pub use for_encoding::ForDecoder;

pub use for_encoding::ForEncoder;

pub use gorilla::GorillaDecoder;

pub use gorilla::GorillaEncodeScratch;

pub use gorilla::GorillaEncoder;

pub use integer::IntegerDecoder;

pub use integer::IntegerEncoder;

pub use integer::VarintDecoder;

pub use integer::VarintEncoder;

pub use patas::PatasDecoder;

pub use patas::PatasEncoder;

pub use pco::PcoDecoder;

pub use pco::PcoEncoder;

pub use plain::PlainDecoder;

pub use plain::PlainEncoder;

pub use rle::RleDecoder;

pub use rle::RleEncoder;

pub use unified::ColumnDecoder;

pub use unified::ColumnEncoder;

pub use unified::DecodedColumn;

pub use unified::EncodedBlock;

pub use unified::EncodingType;

pub use unified::TimestampEncoding;

Modules

adaptive

Adaptive encoding selection — samples data to choose the optimal encoding.

alp

ALP — Adaptive Lossless floating-Point compression (SIGMOD 2024).

bitmap

Bitmap encoding for boolean columns.

chimp

Chimp float encoding (VLDB 2022).

decimal

Encoding for exact decimal columns — the i128 mantissa stream.

delta

Delta-of-delta timestamp encoding.

dictionary

Dictionary encoding for string columns (tags and low-cardinality strings).

error

Encoding error types.

for_encoding

Frame-of-Reference (FOR) encoding for integer columns.

gorilla

Gorilla XOR float encoding (Facebook, 2015).

integer

Integer encoding using Delta + ZigZag + variable-length bit-packing.

patas

Patas float encoding (VLDB 2023).

pco

Pcodec (pco) — Loncaric, Pcodec: Better Compression for Numerical Sequences (2025) — as a block codec for floats and integers.

plain

Plain (uncompressed) encoding for fallback use.

rle

Run-Length Encoding (RLE) for columns with repeated consecutive values.

unified

Unified column encoding API with automatic encoder selection.