Struct CardinalityTracker 

pub struct CardinalityTracker { /* private fields */ }

Real-time cardinality tracker using HyperLogLog sketches

Maintains per-column HLL sketches for sub-microsecond cardinality queries with <1% standard error.

Math

Standard error = 1.04 / sqrt(2^precision)

Precision=14: SE = 0.81%, memory = 16KB per column (dense)
Sparse mode: memory = O(cardinality) for low-cardinality columns

Thread Safety

Uses fine-grained locking per table for concurrent updates across multiple ingestion threads.

Implementations

impl CardinalityTracker

pub fn new() -> Self

Create a new tracker with default precision (14)

pub fn with_precision(precision: u8) -> Self

Create with custom HLL precision

Precision affects accuracy vs memory:

• 10: SE=3.25%, 1KB/column
• 12: SE=1.63%, 4KB/column
• 14: SE=0.81%, 16KB/column (default)
• 16: SE=0.41%, 64KB/column

pub fn set_drift_threshold(&mut self, threshold: f64)

Set drift threshold for cache invalidation

pub fn observe<T: Hash>(&self, table: &str, column: &str, value: &T)

Observe a value for a column (call on INSERT/UPDATE)

O(1) operation - safe to call on every write.

pub fn observe_batch<T: Hash>( &self, table: &str, column: &str, values: impl Iterator<Item = T>, )

Observe multiple values in batch (more efficient for bulk inserts)

pub fn increment_row_count(&self, table: &str, delta: usize)

Increment row count for a table

pub fn estimate(&self, table: &str, column: &str) -> Option<CardinalityEstimate>

Estimate cardinality for a column

O(1) operation - returns sub-microsecond.

pub fn get_table_cardinalities(&self, table: &str) -> HashMap<String, usize>

Get all column cardinalities for a table

pub fn get_row_count(&self, table: &str) -> usize

Get row count estimate for a table

pub fn has_cardinality_drift( &self, table: &str, cached_cardinalities: &HashMap<String, usize>, ) -> bool

Check if cardinality has drifted beyond threshold

Returns true if any column’s cardinality has changed by more than drift_threshold (default 20%).

pub fn merge(&self, table: &str, column: &str, other_hll: &HyperLogLog)

Merge HLL from another tracker (for distributed scenarios)

pub fn clear_table(&self, table: &str)

Clear all tracking data for a table

pub fn memory_usage(&self) -> CardinalityTrackerStats

Get memory usage statistics

Trait Implementations

impl Default for CardinalityTracker

fn default() -> Self

Returns the “default value” for a type.