---
title: "Time-Travel Queries - Quick Reference"
---

# Time-Travel Queries - Quick Reference

## SQL Syntax

### AS OF TIMESTAMP
```sql
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
```sql
SELECT * FROM orders AS OF TRANSACTION 987654;
```

### AS OF SCN
```sql
SELECT * FROM orders AS OF SCN 123456789;
```

### AS OF NOW
```sql
SELECT * FROM orders AS OF NOW;
```

## Rust API

### Query Historical Data
```rust
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
```rust
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
```rust
let row_id = engine.insert_tuple_versioned("orders", tuple)?;
```

### Garbage Collection
```rust
// Auto-GC (default: enabled)
let config = GcConfig::default();

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

## Configuration

```rust
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:
```bash
cargo test --test time_travel_integration_tests
```

Run specific test:
```bash
cargo test test_as_of_transaction
```

## Monitoring

```rust
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
```rust
// 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
```rust
// 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
```rust
// 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())),
    // ...
};
```