Skip to content
HeliosDB HeliosDB Full

Graph Database: API Reference

Graph Database: API Reference

Part of: Graph Database User Guide

Core Data Structures

pub struct Node {
    pub id: NodeId,                                    // Auto-assigned
    pub label: String,                                 // Node type
    pub properties: HashMap<String, serde_json::Value>, // Properties
}


pub struct Edge {
    pub id: EdgeId,                                    // Auto-assigned
    pub source: NodeId,                                // Start node
    pub target: NodeId,                                // End node
    pub label: String,                                 // Relationship type
    pub weight: f64,                                   // Edge weight
    pub properties: HashMap<String, serde_json::Value>, // Properties
}


pub struct Path {
    pub nodes: Vec<NodeId>,      // Nodes in path
    pub edges: Vec<EdgeId>,      // Edges in path
    pub cost: f64,               // Total cost
    pub metadata: HashMap<String, String>, // Additional info
}

GraphStorage Methods

impl GraphStorage {
    // Create new storage
    pub fn new(name: String, config: StorageConfig) -> Self;


    // Add node, returns NodeId
    pub async fn add_vertex(&self, node: Node) -> Result<NodeId>;


    // Add edge, returns EdgeId
    pub async fn add_edge(&self, edge: Edge) -> Result<EdgeId>;


    // Get node by ID
    pub async fn get_vertex(&self, node_id: NodeId) -> Result<Option<Node>>;


    // Get edge by ID
    pub async fn get_edge(&self, edge_id: EdgeId) -> Result<Option<Edge>>;


    // Get outgoing neighbors
    pub async fn get_neighbors(&self, node_id: NodeId) -> Result<Vec<NodeId>>;


    // Get outgoing edges
    pub async fn get_outgoing_edges(&self, node_id: NodeId) -> Result<Vec<Edge>>;


    // Get incoming edges
    pub async fn get_incoming_edges(&self, node_id: NodeId) -> Result<Vec<Edge>>;


    // Find nodes by label
    pub async fn get_vertices_by_label(&self, label: &str) -> Result<Vec<Node>>;


    // Find nodes by property
    pub async fn get_vertices_by_property(
        &self,
        key: &str,
        value: &serde_json::Value
    ) -> Result<Vec<Node>>;


    // Get statistics
    pub async fn get_stats(&self) -> Result<StorageStats>;


    // Optimize storage
    pub async fn optimize(&self) -> Result<()>;


    // Compact storage
    pub async fn compact(&self) -> Result<()>;
}

Cypher Query Execution

use heliosdb_graph::cypher::{CypherExecutor, CypherQuery, QueryResult};


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


// Access results
for row in result.rows {
    let name = row.get("name").unwrap();
    let age = row.get("age").unwrap();
    println!("{}, {}", name, age);
}

Traversal Algorithms

// BFS
pub async fn bfs(
    storage: &GraphStorage,
    start: NodeId,
    options: BfsOptions,
) -> Result<BfsResult>;


pub struct BfsOptions {
    pub max_depth: usize,
    pub max_nodes: usize,
    pub enable_early_termination: bool,
    pub target: Option<NodeId>,
}


pub struct BfsResult {
    pub visited: HashMap<NodeId, usize>,  // NodeId -> depth
    pub total_visited: usize,
    pub max_depth_reached: usize,
    pub duration: Duration,
    pub depth_distribution: HashMap<usize, usize>,
}


// DFS
pub async fn dfs(
    storage: &GraphStorage,
    start: NodeId,
    options: DfsOptions,
) -> Result<DfsResult>;


// Dijkstra
pub async fn dijkstra(
    storage: &GraphStorage,
    source: NodeId,
    target: NodeId,
) -> Result<Option<ShortestPathResult>>;


// A*
pub async fn astar<F>(
    storage: &GraphStorage,
    source: NodeId,
    target: NodeId,
    heuristic: F,
) -> Result<Option<ShortestPathResult>>
where F: Fn(NodeId, NodeId) -> f64;

Graph Algorithms

// PageRank
pub async fn pagerank(
    storage: &GraphStorage,
    nodes: &[NodeId],
    damping: f64,
    iterations: usize,
    tolerance: f64,
) -> Result<HashMap<NodeId, f64>>;


// Centrality
pub async fn degree_centrality(
    storage: &GraphStorage,
    nodes: &[NodeId],
    mode: DegreeMode,
) -> Result<HashMap<NodeId, f64>>;


pub async fn betweenness_centrality(
    storage: &GraphStorage,
    nodes: &[NodeId],
) -> Result<HashMap<NodeId, f64>>;


pub async fn closeness_centrality(
    storage: &GraphStorage,
    nodes: &[NodeId],
) -> Result<HashMap<NodeId, f64>>;


pub async fn eigenvector_centrality(
    storage: &GraphStorage,
    nodes: &[NodeId],
    iterations: usize,
    tolerance: f64,
) -> Result<HashMap<NodeId, f64>>;


// Community Detection
pub async fn louvain(
    storage: &GraphStorage,
    nodes: &[NodeId],
    resolution: f64,
) -> Result<CommunityResult>;


pub async fn label_propagation(
    storage: &GraphStorage,
    nodes: &[NodeId],
    max_iterations: usize,
) -> Result<CommunityResult>;


pub struct CommunityResult {
    pub communities: HashMap<NodeId, usize>,
    pub num_communities: usize,
    pub modularity: f64,
    pub iterations: usize,
}


// Connected Components
pub async fn strongly_connected_components(
    storage: &GraphStorage,
    nodes: &[NodeId],
) -> Result<HashMap<usize, Vec<NodeId>>>;


pub async fn weakly_connected_components(
    storage: &GraphStorage,
    nodes: &[NodeId],
) -> Result<HashMap<usize, Vec<NodeId>>>;

Version: 6.5 Last Updated: November 17, 2025