chronix_encoding/
lib.rs

1//! # chronix-encoding
2//!
3//! Column-oriented encoding and compression for the Chronix time-series database.
4//!
5//! This crate provides type-specific encoders that exploit the statistical
6//! properties of time-series data to achieve high compression ratios:
7//!
8//! | Column type | Encoder | Typical ratio |
9//! |-------------|---------|---------------|
10//! | Timestamps | [`PcoEncoder`] — mode recovery + delta + binned ANS | 2.7–1092× |
11//! | Timestamps | [`DeltaOfDeltaEncoder`] — delta-of-delta + bit-packing | 0.9–63× |
12//! | Floats | [`AlpEncoder`] — decimal reconstruction + FOR bit-packing | 4–20× |
13//! | Floats | [`ChimpEncoder`] / [`GorillaEncoder`] — XOR-based | 1.3–4× |
14//! | Integers | [`IntegerEncoder`] — delta + ZigZag + bit-packing | 4–16× |
15//! | Integers | [`ForEncoder`] — Frame-of-Reference (narrow range) | 4–32× |
16//! | Strings | [`DictionaryEncoder`] — string table + index | 4–64× |
17//! | Booleans | [`BitmapEncoder`] — 1 bit per value | 8× |
18//! | Any | [`PlainEncoder`] — uncompressed fallback | 1× |
19//!
20//! ## Unified API
21//!
22//! [`ColumnEncoder`] / [`ColumnDecoder`] auto-select the best encoding per
23//! column type and transparently fall back to plain when a specialized
24//! encoder cannot achieve sufficient compression.
25//!
26//! ## Adaptive Selection
27//!
28//! [`AdaptiveSelector`] samples values at write time and classifies the data
29//! distribution (`Constant`, `SlowlyVarying`, `Periodic`, `Random`) to pick
30//! the optimal encoder. The choice is stored in column metadata for the decoder.
31//!
32//! ## Design Principles
33//!
34//! 1. **Lossless** — every encoder guarantees bitwise-exact roundtrip.
35//! 2. **Zero-copy** — decoders operate on byte slices where possible.
36//! 3. **Auto-selection** — the unified API picks the best encoder per column.
37//! 4. **Fallback** — plain encoding is used when compression is not beneficial.
38
39#![warn(missing_docs)]
40#![deny(unsafe_code)]
41#![allow(clippy::module_name_repetitions)]
42#![allow(clippy::cast_possible_truncation)]
43#![allow(clippy::cast_sign_loss)]
44#![allow(clippy::cast_lossless)]
45#![allow(clippy::cast_possible_wrap)]
46
47pub mod adaptive;
48pub mod alp;
49pub mod bitmap;
50pub mod chimp;
51pub(crate) mod coding;
52pub mod delta;
53pub mod dictionary;
54pub mod error;
55pub mod for_encoding;
56pub mod gorilla;
57pub mod integer;
58pub mod patas;
59pub mod pco;
60pub mod plain;
61pub mod rle;
62pub(crate) mod simd;
63pub mod unified;
64
65pub use adaptive::{AdaptiveSelector, FloatPattern, IntegerPattern, StringPattern};
66pub use alp::{AlpDecoder, AlpEncoder};
67pub use bitmap::{BitmapDecoder, BitmapEncoder};
68pub use chimp::{Chimp128Decoder, Chimp128Encoder, ChimpDecoder, ChimpEncoder};
69pub use delta::{DeltaOfDeltaDecoder, DeltaOfDeltaEncoder};
70pub use dictionary::{DictionaryDecoder, DictionaryEncoder};
71pub use error::EncodingError;
72pub use for_encoding::{ForDecoder, ForEncoder};
73pub use gorilla::{GorillaDecoder, GorillaEncodeScratch, GorillaEncoder};
74pub use integer::{IntegerDecoder, IntegerEncoder, VarintDecoder, VarintEncoder};
75pub use patas::{PatasDecoder, PatasEncoder};
76pub use pco::{PcoDecoder, PcoEncoder};
77pub use plain::{PlainDecoder, PlainEncoder};
78pub use rle::{RleDecoder, RleEncoder};
79pub use unified::{
80    ColumnDecoder, ColumnEncoder, DecodedColumn, EncodedBlock, EncodingType, TimestampEncoding,
81};
chronix_encoding/lib.rs

chronix_encoding/
lib.rs
