Materialized Views Quick Start Guide

Time to Complete: 5 minutes Prerequisites: Rust 1.75+, HeliosDB installed Last Updated: January 4, 2026

Overview

This guide helps you create and use materialized views in HeliosDB in just 5 minutes.

Step 1: Add Dependency

Add the compute crate to your Cargo.toml:

[dependencies]
heliosdb-compute = "5.0.0"
tokio = { version = "1.0", features = ["full"] }

Step 2: Create a Materialized View

use heliosdb_compute::materialized_views::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create view manager
    let manager = MaterializedViewManager::new();

    // Define a materialized view
    let view = MaterializedView::new(
        "order_summary".to_string(),
        r#"
            SELECT
                customer_id,
                COUNT(*) as order_count,
                SUM(total) as total_spent
            FROM orders
            GROUP BY customer_id
        "#.to_string(),
        RefreshStrategy::Manual,
    );

    // Create the view
    let view_id = manager.create_view(view).await?;
    println!("Created view with ID: {}", view_id);

    // Refresh the view
    manager.refresh_view(view_id).await?;
    println!("View refreshed successfully");

    Ok(())
}

Step 3: Query the Materialized View

// Queries against 'order_summary' are now fast!
let results = execute_query("SELECT * FROM order_summary WHERE total_spent > 1000").await?;

Step 4: Set Up Automatic Refresh

use heliosdb_compute::materialized_views::*;

// Create a view with scheduled refresh (every 5 minutes)
let schedule = RefreshSchedule {
    schedule_type: ScheduleType::Interval { seconds: 300 },
    enabled: true,
    start_time: None,
    end_time: None,
};

let view = MaterializedView::new(
    "realtime_summary".to_string(),
    "SELECT status, COUNT(*) FROM orders GROUP BY status".to_string(),
    RefreshStrategy::Scheduled(schedule),
);

let view_id = manager.create_view(view).await?;
println!("Auto-refresh view created");

Step 5: Monitor Your View

let view = manager.get_view(view_id).await?;

println!("View Statistics:");
println!("  Row count: {}", view.statistics.row_count);
println!("  Last refresh: {}", view.statistics.last_refresh_time);
println!("  Query hits: {}", view.statistics.query_hit_count);

Common Refresh Strategies

// Manual - refresh on demand
RefreshStrategy::Manual

// On-Commit - refresh after each transaction
RefreshStrategy::OnCommit

// Every 5 minutes
RefreshStrategy::Scheduled(RefreshSchedule {
    schedule_type: ScheduleType::Interval { seconds: 300 },
    ..Default::default()
})

// Daily at midnight
RefreshStrategy::Scheduled(RefreshSchedule {
    schedule_type: ScheduleType::Cron {
        expression: "0 0 * * *".to_string(),
    },
    ..Default::default()
})

What’s Next?

Topic	Guide
Complete documentation	USER_GUIDE.md
Common issues	TROUBLESHOOTING.md
Technical details	MATERIALIZED_VIEWS_IMPLEMENTATION.md

Quick Troubleshooting

Issue: View not being used by queries

// Check if view is fresh and active
let view = manager.get_view(view_id).await?;
println!("State: {:?}", view.state);
println!("Is fresh: {}", view.is_fresh());

Issue: Slow refresh

// Use incremental refresh for large views
let engine = IncrementalRefreshEngine::new();
let delta = engine.compute_delta(view_id, &tables, view_size).await?;
engine.apply_delta(&delta).await?;

See Also: README.md | USER_GUIDE.md