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//! | Decimals | [`DecimalEncoder`] — `i128` mantissa over the integer stack | 4–1000× |
17//! | Strings | [`DictionaryEncoder`] — string table + index | 4–64× |
18//! | Booleans | [`BitmapEncoder`] — 1 bit per value | 8× |
19//! | Any | [`PlainEncoder`] — uncompressed fallback | 1× |
20//!
21//! ## Unified API
22//!
23//! [`ColumnEncoder`] / [`ColumnDecoder`] auto-select the best encoding per
24//! column type and transparently fall back to plain when a specialized
25//! encoder cannot achieve sufficient compression.
26//!
27//! ## Adaptive Selection
28//!
29//! [`AdaptiveSelector`] samples values at write time and classifies the data
30//! distribution (`Constant`, `SlowlyVarying`, `Periodic`, `Random`) to pick
31//! the optimal encoder. The choice is stored in column metadata for the decoder.
32//!
33//! ## Design Principles
34//!
35//! 1. **Lossless** — every encoder guarantees bitwise-exact roundtrip.
36//! 2. **Zero-copy** — decoders operate on byte slices where possible.
37//! 3. **Auto-selection** — the unified API picks the best encoder per column.
38//! 4. **Fallback** — plain encoding is used when compression is not beneficial.
39
40#![warn(missing_docs)]
41#![deny(unsafe_code)]
42#![allow(clippy::module_name_repetitions)]
43#![allow(clippy::cast_possible_truncation)]
44#![allow(clippy::cast_sign_loss)]
45#![allow(clippy::cast_lossless)]
46#![allow(clippy::cast_possible_wrap)]
47
48pub mod adaptive;
49pub mod alp;
50pub mod bitmap;
51pub mod chimp;
52pub(crate) mod coding;
53pub mod decimal;
54pub mod delta;
55pub mod dictionary;
56pub mod error;
57pub mod for_encoding;
58pub mod gorilla;
59pub mod integer;
60pub mod patas;
61pub mod pco;
62pub mod plain;
63pub mod rle;
64pub(crate) mod simd;
65pub mod unified;
66
67pub use adaptive::{AdaptiveSelector, FloatPattern, IntegerPattern, StringPattern};
68pub use alp::{AlpDecoder, AlpEncoder};
69pub use bitmap::{BitmapDecoder, BitmapEncoder};
70pub use chimp::{Chimp128Decoder, Chimp128Encoder, ChimpDecoder, ChimpEncoder};
71pub use decimal::{DecimalDecoder, DecimalEncoder};
72pub use delta::{DeltaOfDeltaDecoder, DeltaOfDeltaEncoder};
73pub use dictionary::{DictionaryDecoder, DictionaryEncoder};
74pub use error::EncodingError;
75pub use for_encoding::{ForDecoder, ForEncoder};
76pub use gorilla::{GorillaDecoder, GorillaEncodeScratch, GorillaEncoder};
77pub use integer::{IntegerDecoder, IntegerEncoder, VarintDecoder, VarintEncoder};
78pub use patas::{PatasDecoder, PatasEncoder};
79pub use pco::{PcoDecoder, PcoEncoder};
80pub use plain::{PlainDecoder, PlainEncoder};
81pub use rle::{RleDecoder, RleEncoder};
82pub use unified::{
83    ColumnDecoder, ColumnEncoder, DecodedColumn, EncodedBlock, EncodingType, TimestampEncoding,
84};
chronix_encoding/lib.rs

chronix_encoding/
lib.rs
