Skip to content
agentmemorylabsPublic
forked from GrafeoDB/grafeo

About

Grafeo is a pure-Rust, high-performance graph database that can be embedded as a library or run as a standalone database, with optional in-memory or persistent storage. Grafeo supports both LPG and RDF and all major query languages.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

 
 

Latest commit

 

History

2,789 Commits

Folders and files

Repository files navigation

Grafeo: The embeddable graph database, written in Rust.

CI docs codecov CodSpeed Badge Crates.io PyPI npm wasm NuGet pub.dev Go Web Server License MSRV Python Discord

Grafeo is a graph database built in Rust from the ground up for speed and efficient memory use. It runs embedded as a library or as a standalone server, with in-memory or persistent storage and full ACID transactions.

In graph-bench (which includes workloads inspired by the LDBC Social Network Benchmark), Grafeo answers every benchmark it supports correctly and is among the fastest embedded graph databases; see the per-category results.

The Grafeo Playground: a social network graph next to the GQL query that returns it

Grafeo supports both Labeled Property Graph (LPG) and Resource Description Framework (RDF) data models and all major query languages.

Features

Core Capabilities

  • Dual data model support: LPG and RDF with optimized storage for each
  • Multi-language queries: GQL, Cypher, Gremlin, GraphQL, SPARQL and SQL/PGQ
  • Embeddable with zero external dependencies: no JVM, no Docker, no external processes
  • Multi-language bindings: Python (PyO3), Node.js/TypeScript (napi-rs), Go (CGO), C (FFI), C# (.NET 8 P/Invoke), Dart (dart:ffi), WebAssembly (wasm-bindgen)
  • In-memory and persistent storage modes
  • MVCC transactions with snapshot isolation

Query Languages

  • GQL (ISO/IEC 39075) with Unicode identifiers per spec
  • Cypher (openCypher 9.0)
  • Gremlin (Apache TinkerPop)
  • GraphQL
  • SPARQL (W3C 1.1) with SHACL validation and Ring Index WCOJ planner
  • SQL/PGQ (SQL:2023)
  • EXPLAIN / EXPLAIN ANALYZE across all six languages

Vector Search & AI

  • Vector as a first-class type: Value::Vector(Arc<[f32]>) stored alongside graph data
  • HNSW index: O(log n) approximate nearest neighbor search with tunable recall
  • Distance functions: Cosine, Euclidean, Dot Product, Manhattan (SIMD-accelerated: AVX2, SSE, NEON)
  • Vector quantization: Scalar (f32 to u8), Binary (1-bit) and Product Quantization (8-32x compression)
  • BM25 text search: Full-text inverted index with Unicode tokenizer and stop word removal
  • Hybrid search: Combined text + vector search with Reciprocal Rank Fusion (RRF) or weighted fusion
  • Change data capture: Before/after property snapshots for audit trails and history tracking
  • Hybrid graph+vector queries: Combine graph traversals with vector similarity in GQL and SPARQL
  • Memory-mapped storage: Disk-backed vectors with LRU cache for large datasets
  • Batch operations: Parallel multi-query search via rayon

Performance Features

  • Push-based vectorized execution with adaptive chunk sizing; each query runs on one thread (parallel query execution is planned)
  • Columnar storage with dictionary, delta and RLE compression
  • Cost-based optimizer with DPccp join ordering and histograms
  • Zone maps for intelligent data skipping (including vector zone maps)
  • Transparent spilling for out-of-core processing
  • Streaming execution for large result sets without buffering
  • Bloom filters for efficient membership tests
  • Writable layered compact store: columnar base with mutable overlay, recompact() to merge

Security

  • Encryption at rest (encryption feature): AES-256-GCM for WAL records and .grafeo sections, password-based (Argon2id) or raw-key setup
  • Role-based access control: Admin, ReadWrite, ReadOnly roles enforced across all six query languages
  • Per-graph access grants: scope an identity's access to specific named graphs
  • SHACL validation (shacl feature): W3C Shapes Constraint Language with all 28 Core constraint types and SHACL-SPARQL
  • Resource limits: query timeouts, property size caps, HNSW max_elements bound

Operations & Observability

  • Incremental backup and point-in-time recovery: backup_full, backup_incremental, restore_to_epoch
  • Prometheus metrics (metrics feature): query, transaction, session, cache, and GC counters with text export
  • Change data capture: before/after property snapshots with epoch-bounded retention
  • Tracing (tracing feature): opt-in observability spans and events
  • Bulk export: Arrow IPC, Polars, pandas, GEXF (Gephi), GraphML (Cytoscape, yEd, NetworkX)
  • Bulk import: CSV, JSONL, TSV, Matrix Market (MMIO), Turtle, N-Triples with streaming loaders
Benchmarks

Measured with graph-bench, which includes workloads inspired by the LDBC Social Network Benchmark. These are not official LDBC Benchmark results (see disclaimer).

Full results per category, with every database named: graph-bench results

Query Language & Data Model Support

Query Language LPG RDF
GQL ✅ -
Cypher ✅ -
GraphQL ✅ ✅
Gremlin ✅ -
SPARQL - ✅
SQL/PGQ ✅ -

Grafeo uses a modular translator architecture where query languages are parsed into ASTs, then translated to a unified logical plan that executes against the appropriate storage backend (LPG or RDF).

Data Models

  • LPG (Labeled Property Graph): Nodes with labels and properties, edges with types and properties. Ideal for social networks, knowledge graphs and application data.
  • RDF (Resource Description Framework): Triple-based storage (subject-predicate-object) with SPO/POS/OSP indexes. Ideal for semantic web, linked data and ontology-based applications.

Installation

Rust

cargo add grafeo

Grafeo uses persona-based feature profiles that describe use cases. Compose them freely:

# Default: the deprecated `embedded` profile (see the table)
cargo add grafeo

# Persona profiles
cargo add grafeo --no-default-features --features lpg,ai   # LPG application with search
cargo add grafeo --features rdf                            # Add RDF, SPARQL and SHACL
cargo add grafeo --features analytics                      # Add algorithms, search and bulk import
cargo add grafeo --features enterprise                     # Add metrics and tracing
cargo add grafeo --no-default-features --features lpg,rdf,analytics,ai  # Every language and model

# Or use individual flags
cargo add grafeo --no-default-features --features gql        # Minimal: GQL only
cargo add grafeo --no-default-features --features languages  # All query languages
cargo add grafeo --features embed                            # ONNX embeddings (opt-in, about 17 MB)
Profile Contents Use case
lpg GQL, Cypher, Gremlin, SQL/PGQ, storage (write-ahead log, database file, spill, mmap) Graph applications
rdf RDF triple store, GQL, SPARQL, GraphQL, SHACL, storage Knowledge graphs, linked data
analytics Graph algorithms, vector, text and hybrid search, JSON Lines and Parquet import Graph analytics pipelines
ai Vector, text and hybrid search, change data capture RAG, semantic search, agent memory
edge GQL, lightweight regex WebAssembly, resource-constrained
enterprise Metrics, tracing, async storage (deprecated) Platform operators, observability
embedded GQL, vector, text and hybrid search, change data capture, algorithms, parallel execution, database file, Arrow export The default; deprecated, removed in 0.7.0

The default build has no write-ahead log: commits reach the file at a checkpoint (close() or wal_checkpoint()). Add wal or lpg for commits that survive a crash; the Python, Node.js, C, C#, Dart and Go packages include it. See Installation.

Node.js / TypeScript

npm install @grafeo-db/js

Go

go get github.com/GrafeoDB/grafeo/crates/bindings/go

WebAssembly

npm install @grafeo-db/wasm

C# / .NET

dotnet add package Grafeo

Dart

# pubspec.yaml
dependencies:
  grafeo: ^0.6.3

Python

pip install grafeo
# or with uv
uv add grafeo

With CLI support:

pip install grafeo[cli]
# or with uv
uv add grafeo[cli]

Quick Start

Node.js / TypeScript

As an ES module, with top-level await (CommonJS: const { GrafeoDB } = require('@grafeo-db/js')):

import { GrafeoDB } from '@grafeo-db/js';

// Create an in-memory database
const db = GrafeoDB.create();

// Or open a persistent database
// const db = GrafeoDB.create('./my-graph');

// Create nodes and relationships
await db.execute("INSERT (:Person {name: 'Alix', age: 30})");
await db.execute("INSERT (:Person {name: 'Gus', age: 25})");
await db.execute(`
    MATCH (a:Person {name: 'Alix'}), (b:Person {name: 'Gus'})
    INSERT (a)-[:KNOWS {since: 2020}]->(b)
`);

// Query the graph
const result = await db.execute(`
    MATCH (p:Person)-[:KNOWS]->(friend)
    RETURN p.name, friend.name
`);
console.log(result.toArray()); // [ { 'p.name': 'Alix', 'friend.name': 'Gus' } ]

db.close();

Python

import grafeo

# Create an in-memory database
db = grafeo.GrafeoDB()

# Or open/create a persistent database
# db = grafeo.GrafeoDB("/path/to/database")

# Create nodes using GQL
db.execute("INSERT (:Person {name: 'Alix', age: 30})")
db.execute("INSERT (:Person {name: 'Gus', age: 25})")

# Create a relationship
db.execute("""
    MATCH (a:Person {name: 'Alix'}), (b:Person {name: 'Gus'})
    INSERT (a)-[:KNOWS {since: 2020}]->(b)
""")

# Query the graph
result = db.execute("""
    MATCH (p:Person)-[:KNOWS]->(friend)
    RETURN p.name, friend.name
""")

for row in result:
    print(row)

# Or use the direct API
node = db.create_node(["Person"], {"name": "Harm"})
print(f"Created node with ID: {node.id}")

# Manage labels
db.add_node_label(node.id, "Employee")     # Add a label
db.remove_node_label(node.id, "Contractor") # Remove a label
labels = db.get_node_labels(node.id)        # Get all labels

Admin APIs (Python)

# Database inspection
db.info()           # Overview: mode, counts, persistence
db.detailed_stats() # Memory usage, index counts
db.schema()         # Labels, edge types, property keys
db.validate()       # Integrity check

# Named graphs and schemas
db.create_graph("social")
db.set_graph("social")
db.list_graphs()               # ['social']
db.set_schema("v1")
db.current_schema()            # 'v1'

# Graph projections (filtered virtual views)
db.create_projection("people", node_labels=["Person"], edge_types=["KNOWS"])
db.list_projections()          # ['people']
db.drop_projection("people")

# Data import
db.import_csv("users.csv", "Person", headers=True)
db.import_jsonl("events.jsonl", "Event")

# Backup and restore
db.backup_full("/backups/full")
db.backup_incremental("/backups/incr")
GrafeoDB.restore_to_epoch("/backups/full", epoch=100, output_path="./restored")

# Persistence control
db.save("/path/to/backup")    # Save to disk
db.to_memory()                # Create in-memory copy
GrafeoDB.open_in_memory(path) # Load as in-memory

# WAL management
db.wal_status()      # WAL info
db.wal_checkpoint()  # Force checkpoint

Rust

use grafeo::GrafeoDB;

fn main() {
    // Create an in-memory database
    let db = GrafeoDB::new_in_memory();

    // Or open a persistent database
    // let db = GrafeoDB::open("./my_database").unwrap();

    // Execute GQL queries
    db.execute("INSERT (:Person {name: 'Alix'})").unwrap();

    let result = db.execute("MATCH (p:Person) RETURN p.name").unwrap();
    for row in result.rows() {
        println!("{:?}", row);
    }
}

Vector Search

import grafeo

db = grafeo.GrafeoDB()

# Store documents with embeddings
db.execute("""INSERT (:Document {
    title: 'Graph Databases',
    embedding: vector([0.1, 0.8, 0.3, 0.5])
})""")
db.execute("""INSERT (:Document {
    title: 'Vector Search',
    embedding: vector([0.2, 0.7, 0.4, 0.6])
})""")
db.execute("""INSERT (:Document {
    title: 'Cooking Recipes',
    embedding: vector([0.9, 0.1, 0.2, 0.1])
})""")

# Create an HNSW index for fast approximate search
db.execute("""
    CREATE VECTOR INDEX doc_idx ON :Document(embedding)
    DIMENSION 4 METRIC 'cosine'
""")

# Find similar documents using cosine similarity
query = [0.15, 0.75, 0.35, 0.55]
result = db.execute(f"""
    MATCH (d:Document)
    WHERE cosine_similarity(d.embedding, vector({query})) > 0.9
    RETURN d.title, cosine_similarity(d.embedding, vector({query})) AS score
    ORDER BY score DESC
""")
for row in result:
    print(row)  # Graph Databases, Vector Search (Cooking Recipes filtered out)

Command-Line Interface

Optional admin CLI for operators and DevOps:

# Install with CLI support
uv add grafeo[cli]

# Inspection
grafeo info ./mydb              # Overview: counts, size, mode
grafeo stats ./mydb             # Detailed statistics
grafeo schema ./mydb            # Labels, edge types, property keys
grafeo validate ./mydb          # Integrity check

# Data import
grafeo import csv data.csv --path ./mydb --label Person
grafeo import jsonl events.jsonl --path ./mydb --label Event

# Backup & restore
grafeo backup create ./mydb -o backup
grafeo backup full ./mydb -o /backups/full
grafeo backup incremental ./mydb -o /backups/incr
grafeo backup restore-to-epoch /backups/full --epoch 100 -o ./restored
grafeo backup status /backups/full

# Data export
grafeo data dump ./mydb -o ./export/
grafeo data dump ./mydb -o graph.gexf --export-format gexf
grafeo data dump ./mydb -o graph.graphml --export-format graphml

# WAL management
grafeo wal status ./mydb
grafeo wal checkpoint ./mydb

# Output formats
grafeo info ./mydb --format json  # Machine-readable JSON
grafeo info ./mydb --format table # Human-readable table (default)

Ecosystem

Project Description
grafeo-server HTTP server & web UI: REST API, transactions, single binary (about 48 MB Docker image)
grafeo-web Browser-based Grafeo via WebAssembly with IndexedDB persistence
gwp GQL Wire Protocol: gRPC wire protocol for GQL (ISO/IEC 39075) with client bindings in 5 languages
boltr Bolt Wire Protocol: pure Rust Bolt v5.x implementation, so Bolt drivers connect to Grafeo
grafeo-langchain LangChain integration: graph store, vector store, Graph RAG retrieval
grafeo-llamaindex LlamaIndex integration: PropertyGraphStore, vector search, knowledge graphs
grafeo-mcp Model Context Protocol server: expose Grafeo as tools for LLM agents
grafeo-memory AI memory layer for LLM applications: fact extraction, deduplication, semantic search
anywidget-graph Interactive graph visualization for Python notebooks (Marimo, Jupyter, VS Code, Colab)
anywidget-vector 3D vector/embedding visualization for Python notebooks
playground Interactive browser playground: query in 6 languages, visualize graphs, explore schemas
IDE Graph database IDE in the browser: query tabs, transactions, vector search and 3D views; the data stays on the machine
Grafeo AI Agent memory, MCP tools and LangChain and LlamaIndex stores on Grafeo, in one file
graph-bench Benchmark suite comparing graph databases across 65 LDBC-inspired and custom benchmarks
ann-benchmarks Fork of ann-benchmarks with a Grafeo HNSW adapter for vector search benchmarking

Documentation

Full documentation is available at docs.grafeo.dev. API Stability says which APIs are stable and which are experimental, and the upgrade guides list what to change between versions.

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Sponsors

Thank you to the people who supported Grafeo's development:

Acknowledgments

Grafeo's execution engine draws inspiration from:

  • DuckDB, vectorized push-based execution, morsel-driven parallelism
  • Kuzu, CSR-based adjacency indexing, factorized query processing

License

Apache-2.0

About

Grafeo is a pure-Rust, high-performance graph database that can be embedded as a library or run as a standalone database, with optional in-memory or persistent storage. Grafeo supports both LPG and RDF and all major query languages.

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages