Crate graphmind 

Graphmind Graph Database

A high-performance graph database written in Rust with ~90% OpenCypher query support, RESP (Redis protocol) compatibility, multi-tenancy, HNSW vector search, natural language queries, and graph algorithms. Currently at v0.6.1.

How a Graph Database Works

Unlike relational databases (PostgreSQL, MySQL) that store data in tables with rows and columns, a graph database stores data as nodes (entities) and edges (relationships). This model is natural for connected data: social networks, knowledge graphs, fraud detection.

Relational:                          Graph:
┌──────────┐  ┌──────────────┐       (Alice)──KNOWS──>(Bob)
│ persons  │  │ friendships  │          │                │
│──────────│  │──────────────│       WORKS_AT        WORKS_AT
│ id│ name │  │ from │ to   │          │                │
│ 1 │Alice │  │  1   │  2   │       (Acme)           (Globex)
│ 2 │ Bob  │  │  2   │  3   │
└──────────┘  └──────────────┘

The key advantage: traversing relationships is O(1) per hop (follow a pointer) instead of O(n log n) per JOIN in SQL. This is called index-free adjacency.

Architecture Overview

┌─────────────────────────────────────────────────────────┐
│                    Client Layer                         │
│   RESP (Redis)         HTTP/REST         SDK (Rust/TS)  │
├─────────────────────────────────────────────────────────┤
│                  Query Pipeline                         │
│   Cypher Text ──> PEG Parser ──> AST ──> Planner ──>   │
│   ──> Physical Operators (Volcano Model) ──> Results   │
├─────────────────────────────────────────────────────────┤
│                  Storage Layer                          │
│   In-Memory GraphStore    RocksDB Persistence    WAL   │
│   Vec<Vec<Node>> arena    Column families        fsync  │
│   Adjacency lists         Tenant isolation       CRC32  │
├─────────────────────────────────────────────────────────┤
│                  Extensions                             │
│   HNSW Vector Search   Graph Algorithms   NLQ (LLM)    │
│   Raft Consensus       Multi-Tenancy      Agentic AI   │
└─────────────────────────────────────────────────────────┘

Key Design Decisions (ADRs)

• ADR-007 Volcano Iterator Model: query operators are lazy, pull-based iterators. Each operator’s next() pulls one record at a time from its child — composable and memory-efficient (no intermediate materialization).
• ADR-012 Late Materialization: scan operators produce NodeRef(id) (8 bytes) instead of cloning full nodes. Properties are resolved on-demand. This reduces memory bandwidth during traversals by ~60%.
• ADR-013 Atomic Keyword Rules: PEG grammar uses atomic rules (@{}) for keywords to prevent implicit whitespace consumption before word-boundary checks.
• ADR-015 Graph-Native Planning: cost-based query optimizer using triple-level statistics for cardinality estimation and join ordering.

Modules

Module	Purpose
graph	Property graph data model (nodes, edges, properties, adjacency lists)
query	OpenCypher parser, AST, planner, and Volcano execution engine
protocol	RESP (Redis) wire protocol for client compatibility
persistence	RocksDB storage, WAL, and multi-tenant isolation
raft	Raft consensus for high availability (leader election, log replication)
vector	HNSW approximate nearest neighbor search for vector embeddings
algo	Graph algorithms (PageRank, WCC, SCC, BFS, Dijkstra, etc.)
nlq	Natural language to Cypher translation via LLM providers
agent	Agentic AI enrichment (GAK: Generation-Augmented Knowledge)
rdf	RDF triple store (foundation for SPARQL support)

Rust Concepts Used Throughout

• Ownership & Borrowing: QueryExecutor<'a> borrows &'a GraphStore — the compiler guarantees no data races without runtime locks for read-only queries.
• Algebraic Data Types: PropertyValue enum (tagged union) with exhaustive match — the compiler ensures every variant is handled.
• Trait Objects: Box<dyn PhysicalOperator> for runtime polymorphism in the operator tree.
• Zero-Cost Abstractions: newtype wrappers (NodeId(u64)) provide type safety with no runtime overhead.
• Error Handling: thiserror for library errors, Result<T, E> instead of exceptions.

Example Usage

use graphmind::graph::{GraphStore, Label, PropertyValue};
use std::collections::HashMap;

// Create a new graph store
let mut store = GraphStore::new();

// Create nodes
let alice = store.create_node("Person");
let bob = store.create_node("Person");

// Set properties
if let Some(node) = store.get_node_mut(alice) {
    node.set_property("name", "Alice");
    node.set_property("age", 30i64);
}

// Create edge
let knows_edge = store.create_edge(alice, bob, "KNOWS").unwrap();

// Query by label
let persons = store.get_nodes_by_label(&Label::new("Person"));
assert_eq!(persons.len(), 2);

Re-exports

pub use graph::Edge;

pub use graph::EdgeId;

pub use graph::EdgeType;

pub use graph::GraphError;

pub use graph::GraphResult;

pub use graph::GraphStore;

pub use graph::Label;

pub use graph::Node;

pub use graph::NodeId;

pub use graph::PropertyMap;

pub use graph::PropertyValue;

pub use query::parse_query;

pub use query::Query;

pub use query::QueryEngine;

pub use query::RecordBatch;

pub use protocol::RespServer;

pub use protocol::RespValue;

pub use protocol::ServerConfig;

pub use persistence::AutoEmbedConfig;

pub use persistence::LLMProvider;

pub use persistence::NLQConfig;

pub use persistence::PersistenceError;

pub use persistence::PersistenceManager;

pub use persistence::PersistenceResult;

pub use persistence::PersistentStorage;

pub use persistence::StorageError;

pub use persistence::StorageResult;

pub use persistence::Wal;

pub use persistence::WalEntry;

pub use persistence::WalError;

pub use persistence::WalResult;

pub use audit::AuditLogger;

pub use rbac::Role;

pub use rbac::User;

pub use rbac::UserStore;

pub use tenant_store::TenantStoreManager;

pub use embed::EmbedError;

pub use embed::EmbedPipeline;

pub use embed::EmbedResult;

pub use embed::TextChunk;

pub use nlq::NLQError;

pub use nlq::NLQPipeline;

pub use nlq::NLQResult;

pub use raft::ClusterConfig;

pub use raft::ClusterManager;

pub use raft::GraphStateMachine;

pub use raft::NodeId as RaftNodeIdWithAddr;

pub use raft::RaftError;

pub use raft::RaftNode;

pub use raft::RaftNodeId;

pub use raft::RaftResult;

pub use raft::Request as RaftRequest;

pub use raft::Response as RaftResponse;

pub use rdf::BlankNode;

pub use rdf::GraphToRdfMapper;

pub use rdf::InferenceRule;

pub use rdf::Literal;

pub use rdf::MappingConfig;

pub use rdf::MappingError;

pub use rdf::NamedNode;

pub use rdf::Namespace;

pub use rdf::NamespaceManager;

pub use rdf::Quad;

pub use rdf::QuadPattern;

pub use rdf::RdfFormat;

pub use rdf::RdfObject;

pub use rdf::RdfParser;

pub use rdf::RdfPredicate;

pub use rdf::RdfSerializer;

pub use rdf::RdfStore;

pub use rdf::RdfStoreError;

pub use rdf::RdfStoreResult;

pub use rdf::RdfSubject;

pub use rdf::RdfTerm;

pub use rdf::RdfToGraphMapper;

pub use rdf::RdfsReasoner;

pub use rdf::Triple;

pub use rdf::TriplePattern;

pub use sparql::QuerySolution;

pub use sparql::ResultFormat;

pub use sparql::SparqlEngine;

pub use sparql::SparqlError;

pub use sparql::SparqlExecutor;

pub use sparql::SparqlParser;

pub use sparql::SparqlResult;

pub use sparql::SparqlResults;

pub use vector::DistanceMetric;

pub use vector::IndexKey;

pub use vector::VectorError;

pub use vector::VectorIndex;

pub use vector::VectorIndexManager;

pub use vector::VectorResult;

Modules

agent

Agentic Enrichment

algo

Graph algorithms module

audit

Audit logging for Graphmind

auth

Authentication module for Graphmind

embed

Auto-Embed Pipelines

graph

Property Graph Model – Core Graph Database Implementation

http

HTTP module for Web UI and REST API

index

Property Indexing module

metrics

Prometheus metrics for Graphmind

nlq

Natural Language Querying (NLQ)

persistence

Persistence Layer

protocol

Network Protocol (RESP)

query

Query Processing Pipeline

raft

Raft Consensus for High Availability

rbac

Role-Based Access Control (RBAC) for Graphmind

rdf

RDF (Resource Description Framework) support for Graphmind Graph Database

sharding

Sharding and Distributed Routing module

snapshot

Snapshot export and import for GraphStore.

sparql

SPARQL 1.1 query language support

tenant_store

Multi-tenant graph store manager

vector

Vector Search and AI Integration

Constants

VERSION

Version information

Functions

version

Get version string