Time-Series Native Operations

EnerOS treats time-series data as a kernel-native data type, supporting millions of points per second writes and millisecond-level queries without an external time-series database. This is the direct embodiment of the “Time-Series Native” philosophy: grid voltage, current, and power are inherently time-series data, and the operating system should understand them natively rather than supporting them through external plugins.

The power system is a “time-intensive” domain: PMU data is sampled at 100–120 Hz, fault recording reaches above 10 kHz, and state estimation runs every 100 ms. Traditional architectures rely on external InfluxDB / TimescaleDB, introducing network round-trips and serialization overhead. EnerOS embeds the time-series engine into the kernel, sharing the same memory space as topology and load flow, with a write path as short as 1μs.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│  Agent / Application / Digital Twin                  │
└──────────────────┬──────────────────────────────────┘
                   │ write / query / aggregate
┌──────────────────┴──────────────────────────────────┐
│  eneros-timeseries (kernel time-series engine)       │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ Writer   │ │ Reader   │ │ Compactor│            │
│  └──────────┘ └──────────┘ └──────────┘            │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐            │
│  │ CQ Engine│ │ Retention│ │ Downsamp │            │
│  └──────────┘ └──────────┘ └──────────┘            │
└──────────────────┬──────────────────────────────────┘
                   │ Columnar Storage + Gorilla Encoding
┌──────────────────┴──────────────────────────────────┐
│  LSM-Tree (per-tenant)                               │
│  MemTable → SSTable → Compaction                    │
└─────────────────────────────────────────────────────┘

Data Model

Time-series data consists of three elements: measurement point (tag), timestamp, and field value.

use eneros_timeseries::{Series, Sample, Timestamp, Quality};

let mut series = Series::new("bus_1.voltage");
series.push(Sample::new(ts1, 1.02));
series.push(Sample::new(ts2, 1.025));

// Sample with quality flag
series.push(Sample::with_quality(ts3, 1.03, Quality::Good));
series.push(Sample::with_quality(ts4, 0.98, Quality::Suspect));

Sample Field Reference

Quality Enum

Writing

Supports single-point, batch, and streaming writes:

use eneros_timeseries::TimeSeriesStore;

let store = TimeSeriesStore::open("/var/eneros/tsdb")?;

// Single-point write
store.write("bus_1.voltage", ts, 1.02).await?;

// Write with quality flag
store.write_with_quality("bus_1.voltage", ts, 1.02, Quality::Good).await?;

// Batch write (recommended, 5x higher throughput)
let batch = vec![
    Sample::new(ts1, 1.02),
    Sample::new(ts2, 1.025),
    Sample::new(ts3, 1.03),
];
store.write_batch("bus_1.voltage", batch).await?;

// Multi-tag batch write
let multi_batch = vec![
    ("bus_1.voltage", Sample::new(ts, 1.02)),
    ("bus_1.frequency", Sample::new(ts, 50.01)),
    ("bus_1.load", Sample::new(ts, 50.0)),
];
store.write_multi(multi_batch).await?;

// Streaming write (for real-time collection)
let mut stream = store.stream("bus_1.voltage");
stream.send(Sample::now(1.02)).await?;
stream.flush().await?;

Write API Overview

Querying

use eneros_timeseries::{Query, Range, Aggregation, Filter};

let result = store.query(
    Query::select("bus_1.voltage")
        .range(Range::last(Duration::hours(1)))
        .downsample(Duration::seconds(1), Aggregation::Avg)
        .filter(Filter::quality(Quality::Good))
).await?;

for sample in result {
    println!("{}: {:.4}", sample.timestamp, sample.value);
}

Multi-Tag Query

let multi = store.query(
    Query::select_multi(&["bus_1.voltage", "bus_1.frequency", "bus_1.load"])
        .range(Range::between(t_start, t_end))
        .align(AlignStrategy::Interpolate)
).await?;

for (tag, samples) in multi {
    println!("Tag {}: {} samples", tag, samples.len());
}

Range Types

Filter Types

Aggregation and Downsampling

Built-in common aggregation functions, supporting both tumbling and sliding windows:

// Overall aggregation
let avg = store.aggregate(
    "bus_1.voltage",
    Range::last(Duration::hours(24)),
    Aggregation::Avg,
).await?;

// Tumbling window aggregation
let windowed = store.window_aggregate(
    "bus_1.load",
    Range::last(Duration::hours(24)),
    Duration::hours(1),
    Aggregation::Percentile(95),
).await?;

for window in &windowed {
    println!("{} ~ {}: P95 = {:.2}", window.start, window.end, window.value);
}

// Sliding window aggregation
let sliding = store.sliding_window(
    "bus_1.load",
    Range::last(Duration::hours(1)),
    Duration::minutes(15),  // Window size
    Duration::minutes(5),   // Step
    Aggregation::StdDev,
).await?;

Continuous Queries

Register automatically executed continuous queries to avoid repeated computation:

use eneros_timeseries::ContinuousQuery;

// SQL-style CQ
store.register_cq(
    "voltage_5min_avg",
    "SELECT avg(value) INTO bus_1.voltage_5m FROM bus_1.voltage GROUP BY time(5m)",
).await?;

// Typed CQ
let cq = ContinuousQuery::new("load_p95_hourly")
    .source("bus_1.load")
    .into("bus_1.load_p95_1h")
    .aggregate(Aggregation::Percentile(95))
    .window(Duration::hours(1))
    .build();
store.register_cq_typed(cq).await?;

// List all CQs
let cqs = store.list_cqs().await?;
for cq in &cqs {
    println!("{}: {} (last_run: {:?})", cq.name, cq.sql, cq.last_run);
}

// Drop a CQ
store.drop_cq("voltage_5min_avg").await?;

Data Retention Policy

Supports configuring retention period and precision degradation per measurement point:

use eneros_timeseries::RetentionPolicy;

store.set_retention("bus_1.voltage",
    RetentionPolicy::new()
        .raw_for(Duration::days(7))                              // Raw data retained for 7 days
        .downsampled(Duration::seconds(1), Duration::days(90))   // 1s granularity retained for 90 days
        .downsampled(Duration::minutes(1), Duration::years(5))   // 1min granularity retained for 5 years
        .downsampled(Duration::hours(1), Duration::years(20))    // 1h granularity retained for 20 years
).await?;

// Batch configuration
let policy = RetentionPolicy::default()
    .raw_for(Duration::days(30));
store.set_retention_multi(&["bus_1.*", "bus_2.*"], policy).await?;

RetentionPolicy Tiers

Anomaly Detection

Built-in time-series anomaly detection algorithms that trigger event notifications to Agents:

use eneros_timeseries::{AnomalyDetector, AnomalyKind};

let detector = AnomalyDetector::new("bus_1.voltage")
    .method(AnomalyKind::Spike { threshold: 3.0 })  // 3σ spike
    .method(AnomalyKind::LevelShift { window: 60 })  // 60s mean shift
    .method(AnomalyKind::Flatline { window: 30 })    // 30s flat
    .on_anomaly(|event| {
        log::warn!("Anomaly: {:?} at {}", event.kind, event.timestamp);
    });

store.register_detector(detector).await?;

Storage Engine

The underlying layer uses columnar storage + Gorilla encoding + Delta-of-Delta timestamp compression. A single node can hold 10 years of grid historical data.

Compression Algorithms

LSM-Tree Structure

MemTable (memory)
   │ flush
   ▼
SSTable L0 (disk, 10MB)
   │ compaction
   ▼
SSTable L1 (disk, 100MB)
   │ compaction
   ▼
SSTable L2+ (disk, 1GB+)

Performance Metrics

Test environment: 4 cores / 8GB / Ubuntu 22.04, NVMe SSD.

Configuration Parameters

Time-series-related configuration in eneros.toml:

[timeseries]
# Storage path
data_dir = "/var/eneros/tsdb"
# MemTable size (MB)
memtable_mb = 64
# SSTable compression algorithm: snappy / lz4 / zstd
compression = "lz4"
# Number of compaction threads
compaction_threads = 2
# Default retention period (days)
default_retention_days = 365
# Whether to enable continuous queries
enable_cq = true
# CQ execution interval (seconds)
cq_interval_secs = 10
# Whether to enable anomaly detection
enable_anomaly = true
# Write cache size (MB)
write_buffer_mb = 128

Relationship with Other Capabilities

Related Documentation

• Digital Twin Engine — Time-series data drives twin replay
• IoT Ubiquitous Access — IoT device time-series collection
• Grid Analysis Advanced — State estimation depends on time-series data
• Safety Guard — WORM audit logs
• EnerOS Introduction — Time-Series Native design philosophy