xlog_stats/lib.rs
1//! GPU-resident statistics for query optimization and solver heuristics.
2//!
3//! This crate provides statistics tracking for GPU-resident relations and columns
4//! that are used by the query optimizer and solver heuristics to make informed
5//! decisions about query execution strategies.
6//!
7//! # Core Types
8//!
9//! - [`StatsManager`]: Central coordinator for all relation statistics and join
10//! selectivity tracking.
11//! - [`RelationStats`]: Tracks cardinality, memory usage, access patterns, and
12//! column-level statistics for GPU-resident relations.
13//! - [`ColumnStats`]: Per-column statistics including distinct counts, null counts,
14//! and value ranges for selectivity estimation.
15//! - [`JoinSelectivity`]: Models join behavior between relations for cardinality
16//! estimation.
17//!
18//! # Usage
19//!
20//! ```ignore
21//! use xlog_stats::{StatsManager, RelationStats, ColumnStats};
22//! use xlog_core::{RelId, ScalarType};
23//!
24//! // Create a stats manager and register relations
25//! let mut mgr = StatsManager::new();
26//! mgr.register_relation(RelId(1));
27//! mgr.register_relation(RelId(2));
28//!
29//! // Update statistics
30//! mgr.update_cardinality(RelId(1), 10_000);
31//! mgr.update_cardinality(RelId(2), 5_000);
32//!
33//! // Add column statistics
34//! let mut col_stats = ColumnStats::new(0, ScalarType::I64);
35//! col_stats.update_distinct(500);
36//! col_stats.update_range(0, 1000);
37//! mgr.add_column_stats(RelId(1), col_stats);
38//!
39//! // Estimate join cardinality
40//! let estimate = mgr.estimate_join_cardinality(RelId(1), RelId(2), &[0], &[0]);
41//!
42//! // Record actual join result to improve future estimates
43//! mgr.record_join_result(RelId(1), RelId(2), vec![0], vec![0], 50_000_000, 25_000);
44//!
45//! // Track hot relations for LRU eviction
46//! mgr.record_access(RelId(1));
47//! let hot_rels = mgr.hot_relations(0.5);
48//! ```
49
50mod manager;
51mod stats;
52
53pub use manager::StatsManager;
54pub use manager::StatsSnapshot;
55pub use stats::{ColumnStats, JoinSelectivity, RelationStats};