Struct TimeseriesEngine 

pub struct TimeseriesEngine { /* private fields */ }

Lite timeseries engine.

Not Send — owned by a single task. The NodeDbLite wrapper handles async bridging.

Implementations

impl TimeseriesEngine

pub fn compact_partitions( &mut self, collection: &str, ) -> Option<CompactionResult>

Compact partitions in a collection by merging small adjacent partitions.

Triggers when:

• Partition count > compaction_partition_threshold (default 20), OR
• Total size < 50% of expected size after merge

Merges consecutive sealed partitions in time order. The merged partition contains all rows sorted by timestamp.

pub fn should_append_to_current_partition(&self, collection: &str) -> bool

Check if a collection should use size-based partitioning.

When partition_size_target_bytes > 0, flush appends to the current (last) partition if it hasn’t reached the target size. Otherwise, creates a new partition.

Returns true if the current partition should continue receiving data (i.e., don’t create a new partition on this flush).

pub fn run_maintenance(&mut self, collection: &str) -> MaintenanceResult

Run all maintenance tasks for a collection: compaction + KV store compaction.

Call this during idle periods (no active queries, no active ingestion).

impl TimeseriesEngine

pub fn new() -> Self

Create with Lite defaults.

pub fn with_config(config: TieredPartitionConfig) -> Self

Create with custom config.

pub fn set_battery_state(&mut self, state: BatteryState)

Update battery state (called by host application).

pub fn collection_names(&self) -> Vec<&str>

pub fn row_count(&self, collection: &str) -> usize

pub fn memory_bytes(&self, collection: &str) -> usize

pub fn partition_count(&self, collection: &str) -> usize

pub fn catalog(&self) -> &SeriesCatalog

pub fn config(&self) -> &TieredPartitionConfig

pub fn decode_timestamps(block: &[u8]) -> Vec<i64>

Decode a flushed timestamp block (Gorilla-encoded).

pub fn decode_values(block: &[u8]) -> Vec<f64>

Decode a flushed value block (Gorilla-encoded).

pub fn decode_series_ids(block: &[u8]) -> Vec<SeriesId>

Decode a flushed series_id block (raw LE u64).

impl TimeseriesEngine

pub fn flush(&mut self, collection: &str) -> Option<FlushResult>

Flush a collection’s memtable to Gorilla-compressed KV entries.

impl TimeseriesEngine

pub fn ingest_metric( &mut self, collection: &str, metric_name: &str, tags: Vec<(String, String)>, sample: MetricSample, ) -> bool

Ingest a metric sample.

Returns true if the memtable needs flushing (memory pressure).

Features:

• Pre-sync downsampling: if sync_resolution_ms > 0, accumulates samples per resolution window and emits one averaged sample per window.
• WAL append: if wal_enabled, appends raw sample to WAL for crash safety.
• Battery-aware: if battery_aware and battery is low, doubles the flush threshold to defer I/O.
• Burst detection: if ingestion rate > 10x baseline for > 30s, enters bulk import mode with higher flush threshold.

pub fn ingest_batch( &mut self, collection: &str, metric_name: &str, tags: Vec<(String, String)>, samples: &[MetricSample], ) -> bool

Ingest a batch of samples for one series.

impl TimeseriesEngine

pub fn enforce_storage_budget( &mut self, budget_bytes: u64, policy: BudgetPolicy, ) -> BudgetCheckResult

Check and enforce the storage budget.

Steps (in order, stop when within budget):

1. Compact fragmented partitions (lossless)
2. If still over: downsample oldest data (lossy)
3. Last resort: surface StorageBudgetExceeded warning

Never silently purges data in Pattern C.

pub fn total_storage_bytes(&self) -> u64

Total storage bytes across all collections (partition metadata sizes).

impl TimeseriesEngine

pub fn plan_downsample(&self) -> Vec<DownsamplePlan>

Plan which partitions should be downsampled to save space.

Returns the oldest partitions sorted by min_ts. The caller reads each partition’s data from the KV store, calls downsample_data(), and writes the result back.

pub fn downsample_data( timestamps: &[i64], values: &[f64], interval_ms: i64, ) -> (Vec<i64>, Vec<f64>)

Downsample raw timestamp+value data into coarser resolution.

The caller provides the decoded data from the KV store. This function averages values within each interval_ms bucket and returns the downsampled (timestamp, value) pairs.

This is a pure function — no side effects on the engine state.

pub fn apply_downsample( &mut self, collection: &str, key_prefix: &str, new_row_count: u64, new_size_bytes: u64, )

Apply a completed downsample: update partition metadata after the caller has written the downsampled data back to the KV store.

impl TimeseriesEngine

pub fn effective_sync_resolution(&self) -> u64

Compute the effective sync resolution based on battery state and configured adaptive behavior.

Normal: use sync_resolution_ms from config (0 = raw). Low battery: increase to 60_000 ms (1-minute averages). Charging: use config default.

impl TimeseriesEngine

pub fn export_csv( &self, collection: &str, output_path: &Path, ) -> Result<BackupResult, Error>

Export a collection’s data as CSV (lightweight backup for Lite-C).

Writes timestamps and values from all flushed partitions and the current memtable to a CSV file. The caller provides the output path.

For full Parquet export, use the DataFusion integration layer.

impl TimeseriesEngine

pub fn verify_retention_codec_compat(&self) -> bool

Verify that retention works correctly with cascading codec metadata.

Checks that:

1. Partitions with codec chain metadata (column_stats with cascade codecs) can be retained by sync status.
2. Codec metadata survives the retain-then-purge lifecycle.

Returns true if all partitions have valid metadata.

impl TimeseriesEngine

pub fn scan( &self, collection: &str, range: &TimeRange, ) -> Vec<(i64, f64, SeriesId)>

Scan metric samples in a time range.

pub fn aggregate_by_bucket( &self, collection: &str, range: &TimeRange, bucket_ms: i64, ) -> Vec<(i64, u64, f64, f64, f64)>

Aggregate over a time range with time_bucket grouping.

impl TimeseriesEngine

pub fn purge_before_ms( &mut self, collection: &str, cutoff_ms: i64, ) -> Vec<String>

Drop the partitions of collection whose max_ts < cutoff_ms.

Unlike apply_retention, this method takes an explicit cutoff rather than reading it from config.retention_period_ms. Used by EnforceTimeseriesRetention, which names one collection and its cutoff. Other collections are untouched.

pub fn apply_retention(&mut self, now_ms: i64) -> Vec<String>

Drop partitions older than the retention period.

pub fn apply_retention_with_sync( &mut self, now_ms: i64, ) -> (Vec<String>, Vec<UnsyncedDropWarning>)

Apply retention with sync-awareness.

Default behavior (retain_until_synced = false): drops by age. Guarded behavior (retain_until_synced = true): keeps unsynced data.

impl TimeseriesEngine

pub fn sync_watermark(&self, series_id: SeriesId) -> u64

Get the sync watermark for a series.

pub fn acknowledge_sync(&mut self, collection: &str, max_synced_ts: u64)

Update sync watermark after Origin acknowledges a push.

pub fn export_watermarks(&self) -> &HashMap<SeriesId, u64>

Get all current sync watermarks (for persistence).

pub fn import_watermarks(&mut self, watermarks: HashMap<SeriesId, u64>)

Import watermarks from the KV store (cold start restore).

pub fn dirty_collections(&self) -> Vec<&str>

Get collections that have unsynced data.

pub fn assign_sync_lsn(&mut self) -> u64

Assign a sync LSN and advance the counter.

pub fn build_sync_payload( &mut self, collection: &str, lite_id: &str, ) -> Option<TimeseriesPushMsg>

Build a sync push payload for a collection.

pub fn sync_interval_ms(&self) -> u64

Get the configured sync interval in milliseconds.

impl TimeseriesEngine

pub fn truncate_collection(&mut self, collection: &str) -> usize

Remove every sample of collection: the memtable, every flushed partition, the pending downsample windows, and the WAL entries that have not reached the flush watermark. The series catalog is shared across collections and stays as it is. Returns the number of rows that existed across the memtable and partitions; a collection the engine never saw reports zero.

impl TimeseriesEngine

pub fn pending_wal_entries(&self, since_seq: u64) -> &[WalEntry]

Get pending WAL entries (for persistence to the KV store by the caller).

pub fn advance_wal_watermark(&mut self, watermark: u64)

Advance the WAL watermark after successful persistence.

pub fn compact_wal(&mut self)

Compact the WAL by removing entries below the flush watermark.

pub fn replay_wal(&mut self, entries: &[WalEntry])

Replay WAL entries after a crash. Called on cold start.

pub fn wal_seq(&self) -> u64

Current WAL sequence number.

pub fn wal_watermark(&self) -> u64

Current WAL flush watermark.

Trait Implementations

impl Default for TimeseriesEngine

fn default() -> Self

Returns the “default value” for a type.