Struct ColumnStore 

pub struct ColumnStore { /* private fields */ }

Column store for high-performance filtering.

Implementations

impl ColumnStore

pub fn batch_update(&mut self, updates: &[BatchUpdate]) -> BatchUpdateResult

Performs batch updates with optimized cache locality.

pub fn batch_update_same_value( &mut self, pks: &[i64], column: &str, value: &ColumnValue, ) -> BatchUpdateResult

Batch update with same value for multiple primary keys.

pub fn set_ttl( &mut self, pk: i64, ttl_seconds: u64, ) -> Result<(), ColumnStoreError>

Sets a TTL (Time To Live) on a row.

Errors

Returns an error when pk is missing or points to a deleted row.

pub fn expire_rows(&mut self) -> ExpireResult

Expires all rows that have passed their TTL.

pub fn upsert( &mut self, values: &[(&str, ColumnValue)], ) -> Result<UpsertResult, ColumnStoreError>

Upsert: inserts a new row or updates an existing one.

Errors

Returns an error when primary key constraints are violated, when a referenced column does not exist, or when types mismatch.

pub fn batch_upsert( &mut self, rows: &[Vec<(&str, ColumnValue)>], ) -> BatchUpsertResult

Batch upsert: inserts or updates multiple rows.

impl ColumnStore

pub fn filter_eq_int(&self, column: &str, value: i64) -> Vec<usize>

Filters rows by equality on an integer column.

Returns a vector of row indices that match. Excludes deleted rows.

pub fn filter_eq_string(&self, column: &str, value: &str) -> Vec<usize>

Filters rows by equality on a string column.

Returns a vector of row indices that match. Excludes deleted rows.

pub fn filter_gt_int(&self, column: &str, threshold: i64) -> Vec<usize>

Filters rows by range on an integer column (value > threshold).

Returns a vector of row indices that match. Excludes deleted rows.

pub fn filter_lt_int(&self, column: &str, threshold: i64) -> Vec<usize>

Filters rows by range on an integer column (value < threshold).

Excludes deleted rows.

pub fn filter_range_int(&self, column: &str, low: i64, high: i64) -> Vec<usize>

Filters rows by range on an integer column (low < value < high).

Excludes deleted rows.

pub fn filter_in_string(&self, column: &str, values: &[&str]) -> Vec<usize>

Filters rows by IN clause on a string column.

Returns a vector of row indices that match any of the values. Excludes deleted rows.

pub fn count_eq_int(&self, column: &str, value: i64) -> usize

Counts rows matching equality on an integer column.

More efficient than filter_eq_int().len() as it doesn’t allocate. Excludes deleted rows.

pub fn count_eq_string(&self, column: &str, value: &str) -> usize

Counts rows matching equality on a string column. Excludes deleted rows.

pub fn filter_eq_int_bitmap(&self, column: &str, value: i64) -> RoaringBitmap

Filters rows by equality on an integer column, returning a bitmap.

Uses RoaringBitmap for memory-efficient storage of matching indices. Useful for combining multiple filters with AND/OR operations.

Note

Row indices are safely converted to u32 for RoaringBitmap. This limits stores to ~4B rows. Indices >= u32::MAX are safely skipped (not truncated).

pub fn filter_eq_string_bitmap( &self, column: &str, value: &str, ) -> RoaringBitmap

Filters rows by equality on a string column, returning a bitmap.

Indices >= u32::MAX are safely skipped.

pub fn filter_range_int_bitmap( &self, column: &str, low: i64, high: i64, ) -> RoaringBitmap

Filters rows by range on an integer column, returning a bitmap.

Indices >= u32::MAX are safely skipped.

pub fn bitmap_and(a: &RoaringBitmap, b: &RoaringBitmap) -> RoaringBitmap

Combines two filter results using AND.

Returns indices that are in both bitmaps.

pub fn bitmap_or(a: &RoaringBitmap, b: &RoaringBitmap) -> RoaringBitmap

Combines two filter results using OR.

Returns indices that are in either bitmap.

impl ColumnStore

pub fn vacuum(&mut self, _config: VacuumConfig) -> VacuumStats

Runs vacuum to remove tombstones and compact data.

This operation removes deleted rows from the column store, reclaiming space and improving query performance. The operation is done in-place by building new column vectors without the deleted rows.

Arguments

• _config - Vacuum configuration (batch_size, sync options)

Returns

Statistics about the vacuum operation.

pub fn should_vacuum(&self, threshold: f64) -> bool

Returns whether vacuum is recommended based on tombstone ratio.

Arguments

• threshold - Ratio of deleted rows to trigger vacuum (0.0-1.0)

pub fn is_row_deleted_bitmap(&self, row_idx: usize) -> bool

Checks if a row is deleted using RoaringBitmap (O(1) lookup).

This is faster than FxHashSet for large deletion sets.

pub fn live_row_indices(&self) -> impl Iterator<Item = usize> + '_

Returns an iterator over live (non-deleted) row indices.

Uses RoaringBitmap for efficient filtering.

pub fn deletion_bitmap(&self) -> &RoaringBitmap

Returns the deletion bitmap for advanced filtering operations.

pub fn deleted_count_bitmap(&self) -> u64

Returns the number of deleted rows using the bitmap (O(1)).

impl ColumnStore

pub fn new() -> Self

Creates a new empty column store.

pub fn with_schema(fields: &[(&str, ColumnType)]) -> Self

Creates a column store with pre-defined indexed fields.

pub fn with_primary_key( fields: &[(&str, ColumnType)], pk_column: &str, ) -> Result<Self>

Creates a column store with a primary key for O(1) lookups.

Errors

Returns Error::ColumnStoreError if pk_column is not found in fields or is not of type Int.

pub fn primary_key_column(&self) -> Option<&str>

Returns the primary key column name if set.

pub fn add_column(&mut self, name: &str, col_type: ColumnType)

Adds a new column to the store.

pub fn row_count(&self) -> usize

Returns the total number of rows in the store (including deleted/tombstoned rows).

pub fn active_row_count(&self) -> usize

Returns the number of active (non-deleted) rows in the store.

pub fn deleted_row_count(&self) -> usize

Returns the number of deleted (tombstoned) rows.

pub fn string_table(&self) -> &StringTable

Returns the string table for string interning.

pub fn string_table_mut(&mut self) -> &mut StringTable

Returns a mutable reference to the string table.

pub fn push_row_unchecked(&mut self, values: &[(&str, ColumnValue)])

Pushes values for a new row (low-level, no validation).

pub fn push_row(&mut self, values: &[(&str, ColumnValue)])

Convenience alias for push_row_unchecked().

pub fn insert_row( &mut self, values: &[(&str, ColumnValue)], ) -> Result<usize, ColumnStoreError>

Inserts a row with primary key validation and index update.

Errors

Returns an error if the primary key is missing, duplicated, or any provided value does not match the target column type.

pub fn get_row_idx_by_pk(&self, pk: i64) -> Option<usize>

Gets the row index by primary key value - O(1) lookup.

pub fn delete_by_pk(&mut self, pk: i64) -> bool

Deletes a row by primary key value.

Also clears any TTL metadata to prevent false-positive expirations. Updates both FxHashSet and RoaringBitmap (EPIC-043 US-002).

pub fn update_by_pk( &mut self, pk: i64, column: &str, value: ColumnValue, ) -> Result<(), ColumnStoreError>

Updates a single column value for a row identified by primary key - O(1).

Errors

Returns an error if the row does not exist, the column does not exist, the update targets the primary-key column, or the value type mismatches the column type.

pub fn update_multi_by_pk( &mut self, pk: i64, updates: &[(&str, ColumnValue)], ) -> Result<(), ColumnStoreError>

Updates multiple columns atomically for a row identified by primary key.

Panics

This function will not panic under normal operation. The internal expect is guarded by prior validation that all columns exist.

Errors

Returns an error if the row does not exist, one of the columns does not exist, one update attempts to modify the primary key, or a value type mismatches its target column type.

pub fn get_column(&self, name: &str) -> Option<&TypedColumn>

Gets a column by name.

pub fn column_names(&self) -> impl Iterator<Item = &str>

Returns an iterator over column names.

pub fn get_value_as_json(&self, column: &str, row_idx: usize) -> Option<Value>

Gets a value from a column at a specific row index as JSON.

Trait Implementations

impl Debug for ColumnStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for ColumnStore

fn default() -> ColumnStore

Returns the “default value” for a type.