Time-Travel Queries - Quick Reference

SQL Syntax

AS OF TIMESTAMP

SELECT * FROM orders AS OF TIMESTAMP '2025-11-15 06:00:00';
SELECT * FROM orders AS OF TIMESTAMP '2025-11-15T06:00:00';

AS OF TRANSACTION

SELECT * FROM orders AS OF TRANSACTION 987654;

AS OF SCN

SELECT * FROM orders AS OF SCN 123456789;

AS OF NOW

SELECT * FROM orders AS OF NOW;

Rust API

Query Historical Data

let plan = LogicalPlan::Scan {
    table_name: "orders".to_string(),
    schema: Arc::new(schema),
    projection: None,
    as_of: Some(AsOfClause::Transaction(100)),
};
let results = executor.execute(&plan)?;

Direct Snapshot Access

let snapshot_mgr = engine.snapshot_manager();
let snapshot_ts = snapshot_mgr.resolve_as_of(&AsOfClause::Scn(123))?;
let tuples = engine.scan_table_at_snapshot("orders", snapshot_ts)?;

Insert Versioned Data

let row_id = engine.insert_tuple_versioned("orders", tuple)?;

Garbage Collection

// Auto-GC (default: enabled)
let config = GcConfig::default();

// Manual GC
let removed = engine.snapshot_manager().gc_old_snapshots()?;

Key Files

Core: /home/claude/HeliosDB Nano/src/storage/time_travel.rs
Integration: /home/claude/HeliosDB Nano/src/storage/engine.rs
Executor: /home/claude/HeliosDB Nano/src/sql/executor.rs
Tests: /home/claude/HeliosDB Nano/tests/time_travel_integration_tests.rs
Parser: /home/claude/HeliosDB Nano/src/sql/phase3/time_travel.rs

Configuration

use heliosdb_nano::storage::GcConfig;

let gc_config = GcConfig {
    min_retention_seconds: 3600,  // 1 hour
    max_snapshots: 1000,
    auto_gc_enabled: true,
};

Error Messages

Error	Meaning
”Transaction X not found or has been garbage collected”	Transaction ID has been GC’d or never existed
”No snapshot found for timestamp ’…’”	No snapshot exists at or before that time
”Invalid timestamp format: …”	Timestamp string couldn’t be parsed
”SCN X not found or has been garbage collected”	SCN has been GC’d or never existed

Performance Tips

Use TXN/SCN over TIMESTAMP: Faster resolution (no string parsing)
Enable auto-GC: Prevents metadata bloat
Tune retention: Balance history needs vs performance
Target overhead: <2x vs non-time-travel queries

Testing

Run time-travel tests:

cargo test --test time_travel_integration_tests

Run specific test:

cargo test test_as_of_transaction

Monitoring

let mgr = engine.snapshot_manager();
println!("Snapshots: {}", mgr.snapshot_count());
println!("Current SCN: {}", mgr.current_scn());
println!("Current TXN: {}", mgr.current_transaction_id());

Examples

Query Past State

// See orders as they existed at transaction 50
let plan = LogicalPlan::Scan {
    table_name: "orders".to_string(),
    schema: Arc::new(schema),
    projection: None,
    as_of: Some(AsOfClause::Transaction(50)),
};

Audit Trail

// Compare current vs historical
let current = executor.execute(&current_plan)?;
let historical = executor.execute(&historical_plan)?;
let changes = compare_states(&current, &historical);

Point-in-Time Recovery

// Get data before incident
let snapshot_mgr = engine.snapshot_manager();
let incident_time = "2025-11-15 05:59:00";
let plan = LogicalPlan::Scan {
    as_of: Some(AsOfClause::Timestamp(incident_time.to_string())),
    // ...
};