vortex_compressor/compressor/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Cascading array compression implementation.
5
6mod cascade;
7mod constant;
8mod sample;
9mod select;
10mod structural;
11
12use crate::builtins::IntDictScheme;
13use crate::scheme::ChildSelection;
14use crate::scheme::DescendantExclusion;
15use crate::scheme::Scheme;
16use crate::scheme::SchemeExt;
17use crate::scheme::SchemeId;
18
19/// Synthetic scheme ID used for the compressor's own root-level cascading.
20pub(crate) const ROOT_SCHEME_ID: SchemeId = SchemeId {
21    name: "vortex.compressor.root",
22};
23
24/// The main compressor type implementing cascading adaptive compression.
25///
26/// This compressor applies adaptive compression [`Scheme`]s to arrays based on their data types and
27/// characteristics. It recursively compresses nested structures like structs and lists, and chooses
28/// optimal compression schemes for leaf types.
29///
30/// The compressor works by:
31/// 1. Canonicalizing input arrays to a standard representation.
32/// 2. Pre-filtering schemes by [`Scheme::matches`] and exclusion rules.
33/// 3. Evaluating each matching scheme's compression estimate and resolving deferred work.
34/// 4. Compressing with the best scheme and verifying the result is smaller.
35///
36/// No scheme may appear twice in a cascade chain. The compressor enforces this automatically
37/// along with push/pull exclusion rules declared by each scheme.
38///
39/// Downstream crates usually wrap this type with a preconfigured scheme set. Use it directly when
40/// embedding a custom fixed scheme list or testing scheme interactions.
41#[derive(Debug, Clone)]
42pub struct CascadingCompressor {
43    /// The enabled compression schemes.
44    schemes: Vec<&'static dyn Scheme>,
45
46    /// Descendant exclusion rules for the compressor's own cascading (e.g. excluding Dict from
47    /// list offsets).
48    root_exclusions: Vec<DescendantExclusion>,
49}
50
51impl CascadingCompressor {
52    /// Creates a new compressor with the given schemes.
53    ///
54    /// Root-level exclusion rules (e.g. excluding Dict from list offsets) are built automatically.
55    pub fn new(schemes: Vec<&'static dyn Scheme>) -> Self {
56        // Root exclusion: exclude IntDict from list/listview offsets (monotonically
57        // increasing data where dictionary encoding is wasteful).
58        let root_exclusions = vec![DescendantExclusion {
59            excluded: IntDictScheme.id(),
60            children: ChildSelection::One(structural::root_list_children::OFFSETS),
61        }];
62
63        Self {
64            schemes,
65            root_exclusions,
66        }
67    }
68}
69
70// NB: Cascading compression logic is located in `vortex-compressor/src/compressor/cascade.rs`.
71
72#[cfg(test)]
73mod tests;
vortex_compressor/compressor/mod.rs

vortex_compressor/compressor/
mod.rs
