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