oxirs_vec/tree_indices.rs
1//! Tree-based indices for efficient nearest neighbor search
2//!
3//! **EXPERIMENTAL**: These tree implementations are currently experimental
4//! and have known limitations with large datasets or specific configurations.
5//! For production use, prefer HNSW, IVF, or LSH indices instead.
6//!
7//! ## Known Limitations
8//! - Tree construction uses recursion with conservative depth limits (20 levels)
9//! - Best suited for moderate-sized datasets (< 100K vectors)
10//! - May encounter stack overflow on systems with very small stack sizes
11//! - Performance degrades in high-dimensional spaces (> 128 dimensions)
12//!
13//! ## Recommended Alternatives
14//! - For most use cases: Use `HnswIndex` (Hierarchical Navigable Small World)
15//! - For very large datasets: Use `IVFIndex` (Inverted File Index)
16//! - For approximate search: Use `LSHIndex` (Locality Sensitive Hashing)
17//!
18//! This module implements various tree data structures:
19//! - Ball Tree: Efficient for arbitrary metrics
20//! - KD-Tree: Classic space partitioning tree
21//! - VP-Tree: Vantage point tree for metric spaces
22//! - Cover Tree: Navigating nets with provable bounds
23//! - Random Projection Trees: Randomized space partitioning
24//!
25//! This module is a thin facade. The implementation is split across:
26//! - [`crate::tree_indices_types`] — [`TreeIndexConfig`], [`TreeType`], [`DistanceMetric`].
27//! - [`crate::tree_indices_balltree`] — the [`BallTree`].
28//! - [`crate::tree_indices_kdtree`] — the [`KdTree`].
29//! - [`crate::tree_indices_vptree`] — the [`VpTree`].
30//! - [`crate::tree_indices_covertree`] — the [`CoverTree`].
31//! - [`crate::tree_indices_rptree`] — the [`RandomProjectionTree`].
32//! - [`crate::tree_indices_unified`] — the unified [`TreeIndex`] dispatcher.
33
34pub use crate::tree_indices_balltree::BallTree;
35pub use crate::tree_indices_covertree::CoverTree;
36pub use crate::tree_indices_kdtree::KdTree;
37pub use crate::tree_indices_rptree::RandomProjectionTree;
38pub use crate::tree_indices_types::{DistanceMetric, TreeIndexConfig, TreeType};
39pub use crate::tree_indices_unified::TreeIndex;
40pub use crate::tree_indices_vptree::VpTree;