Skip to content
HeliosDB HeliosDB Full

Graph Database: Quick Start (15 Minutes)

Graph Database: Quick Start (15 Minutes)

Part of: Graph Database User Guide

Prerequisites

Terminal window
# Install HeliosDB (if not already installed)
cargo install heliosdb-cli


# Or build from source
git clone https://github.com/heliosdb/heliosdb
cd heliosdb
cargo build --release

Step 1: Create a Graph Schema (3 minutes)

Let’s build a simple social network graph:

use heliosdb_graph::{GraphStorage, Node, Edge, StorageConfig};
use std::collections::HashMap;
use serde_json::json;


#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create storage with default configuration
    let config = StorageConfig::default();
    let storage = GraphStorage::new("social_network".to_string(), config);


    println!("Graph storage created: social_network");
    Ok(())
}

Step 2: Insert Nodes and Edges (5 minutes)

// Create Person nodes
let alice = Node {
    id: 0, // Auto-assigned
    label: "Person".to_string(),
    properties: HashMap::from([
        ("name".to_string(), json!("Alice")),
        ("age".to_string(), json!(28)),
        ("city".to_string(), json!("San Francisco")),
    ]),
};


let bob = Node {
    id: 0,
    label: "Person".to_string(),
    properties: HashMap::from([
        ("name".to_string(), json!("Bob")),
        ("age".to_string(), json!(32)),
        ("city".to_string(), json!("New York")),
    ]),
};


let charlie = Node {
    id: 0,
    label: "Person".to_string(),
    properties: HashMap::from([
        ("name".to_string(), json!("Charlie")),
        ("age".to_string(), json!(25)),
        ("city".to_string(), json!("San Francisco")),
    ]),
};


// Add nodes to graph
let alice_id = storage.add_vertex(alice).await?;
let bob_id = storage.add_vertex(bob).await?;
let charlie_id = storage.add_vertex(charlie).await?;


println!("Added 3 nodes: Alice={}, Bob={}, Charlie={}",
         alice_id, bob_id, charlie_id);


// Create FRIEND_OF relationships
let edge1 = Edge {
    id: 0,
    source: alice_id,
    target: bob_id,
    label: "FRIEND_OF".to_string(),
    weight: 1.0,
    properties: HashMap::from([
        ("since".to_string(), json!("2020-01-15")),
    ]),
};


let edge2 = Edge {
    id: 0,
    source: alice_id,
    target: charlie_id,
    label: "FRIEND_OF".to_string(),
    weight: 1.0,
    properties: HashMap::from([
        ("since".to_string(), json!("2021-06-20")),
    ]),
};


let edge3 = Edge {
    id: 0,
    source: bob_id,
    target: charlie_id,
    label: "FRIEND_OF".to_string(),
    weight: 1.0,
    properties: HashMap::from([
        ("since".to_string(), json!("2021-09-10")),
    ]),
};


storage.add_edge(edge1).await?;
storage.add_edge(edge2).await?;
storage.add_edge(edge3).await?;


println!("Added 3 friendships");

Step 3: First Cypher Query (3 minutes)

Find all friends of Alice:

use heliosdb_graph::cypher::{
    CypherQuery, CypherExecutor, MatchClause, Pattern,
    NodePattern, RelationshipPattern, Direction, PathLength,
    ReturnClause, ReturnItem, Expression
};


let query = CypherQuery {
    match_clause: Some(MatchClause {
        patterns: vec![Pattern {
            nodes: vec![
                NodePattern {
                    variable: "alice".to_string(),
                    labels: vec!["Person".to_string()],
                    properties: HashMap::from([
                        ("name".to_string(), json!("Alice")),
                    ]),
                },
                NodePattern {
                    variable: "friend".to_string(),
                    labels: vec!["Person".to_string()],
                    properties: HashMap::new(),
                },
            ],
            relationships: vec![RelationshipPattern {
                variable: None,
                types: vec!["FRIEND_OF".to_string()],
                direction: Direction::Outgoing,
                properties: HashMap::new(),
                length: PathLength::Fixed(1),
            }],
        }],
    }),
    where_clause: None,
    return_clause: ReturnClause {
        items: vec![
            ReturnItem {
                expression: Expression::Property {
                    variable: "friend".to_string(),
                    property: "name".to_string(),
                },
                alias: Some("friend_name".to_string()),
            },
            ReturnItem {
                expression: Expression::Property {
                    variable: "friend".to_string(),
                    property: "age".to_string(),
                },
                alias: Some("friend_age".to_string()),
            },
        ],
        distinct: false,
    },
    order_by: None,
    limit: None,
    skip: None,
};


let executor = CypherExecutor::new(storage.clone());
let result = executor.execute(&query).await?;


println!("Alice's friends:");
for row in result.rows {
    println!("  - {}, age {}",
             row.get("friend_name").unwrap(),
             row.get("friend_age").unwrap());
}


// Output:
// Alice's friends:
//   - Bob, age 32
//   - Charlie, age 25

Step 4: Pattern Matching (4 minutes)

Find friends of friends (2-hop traversal):

use heliosdb_graph::traversal::{bfs, BfsOptions};


let options = BfsOptions {
    max_depth: 2,
    max_nodes: 1000,
    enable_early_termination: false,
    target: None,
};


let result = bfs(&storage, alice_id, options).await?;


println!("Friends of friends (up to 2 hops from Alice):");
for (node_id, depth) in result.visited {
    if depth == 2 {
        if let Some(node) = storage.get_vertex(node_id).await? {
            println!("  - {} (depth {})",
                     node.properties.get("name").unwrap(),
                     depth);
        }
    }
}

Congratulations! You’ve created a graph, added nodes/edges, and queried relationships. Continue reading for advanced features.

Version: 6.5 Last Updated: November 17, 2025