cypherlite-query 1.2.1

Cypher query engine with parser, planner, and executor for CypherLite
Documentation 
        (\-.
        / _`>  CypherLite
       / /
      / /      Lightweight Embedded
     / /       Graph Database
    / /
   (,/
    ``

A lightweight, embedded, single-file graph database engine written in Rust. CypherLite brings zero-config, single-file deployment to the graph database ecosystem — with full ACID compliance, native property graph support, temporal queries, subgraph entities, hyperedges, and a trait-based plugin system.

Available in: 中文 | हिन्दी | Español | Français | العربية | বাংলা | Português | Русский | 한국어

Features

Storage Engine

  • ACID Transactions — Full atomicity, consistency, isolation, and durability via Write-Ahead Logging
  • Single-Writer / Multiple-Reader — SQLite-compatible concurrency model using parking_lot
  • Snapshot Isolation — WAL frame index-based MVCC for consistent reads
  • B+Tree Storage — O(log n) node and edge lookup with index-free adjacency
  • Crash Recovery — WAL replay on startup for consistency after unexpected shutdown
  • Property Graph — Nodes and edges with typed properties: Null, Bool, Int64, Float64, String, Bytes, Array
  • Embedded Library — No server process, zero configuration, single .cyl file

Query Engine (Cypher)

  • openCypher Subset — MATCH, CREATE, MERGE, SET, DELETE, RETURN, WHERE, WITH, ORDER BY
  • Recursive Descent Parser — Hand-written parser with Pratt expression parsing and 28+ keywords
  • Semantic Analysis — Variable scope validation and label/type resolution
  • Cost-Based Optimizer — Logical-to-physical plan conversion with predicate pushdown
  • Volcano Executor — Iterator-based execution with 12 operators
  • Three-Valued Logic — Full NULL propagation per openCypher specification
  • Inline Property Filter — MATCH (n:Label {key: value}) pattern support

Temporal Features

  • AT TIME Queries — Point-in-time graph state retrieval
  • Version Store — Immutable property version chain per node and edge
  • Temporal Edge Versioning — Edge creation/deletion timestamps with temporal relationship queries
  • Temporal Aggregation — Time-range queries with aggregate functions over versioned data

Subgraph & Hyperedge

  • SubgraphStore — Named subgraphs as first-class entities stored alongside nodes and edges
  • CREATE / MATCH SNAPSHOT — Capture and query named subgraph entities
  • Native Hyperedges — N:M relations connecting arbitrary numbers of nodes
  • HYPEREDGE Syntax — CREATE HYPEREDGE :TYPE CONNECTING (n1), (n2), (n3)
  • TemporalRef — Hyperedge members carry temporal reference metadata

Plugin System

  • ScalarFunction — Register custom query functions callable in Cypher expressions
  • IndexPlugin — Pluggable custom index implementations (e.g., HNSW vector index)
  • Serializer — Custom import/export format plugins (e.g., JSON-LD, GraphML)
  • Trigger — Before/after hooks for CREATE, DELETE, SET operations with rollback support
  • PluginRegistry — Generic, thread-safe HashMap-based registry (Send + Sync)
  • Zero Overhead — plugin feature flag; cfg-gated, no cost when disabled

FFI Bindings

  • C ABI — Static library with a C header for embedding in any C-compatible project
  • Python — PyO3-based bindings via pip install cypherlite
  • Go — CGo bindings via go get github.com/Epsilondelta-ai/CypherLite/bindings/go/cypherlite
  • Node.js — napi-rs native addon via npm install cypherlite

Quick Start

Rust

# Cargo.toml
[dependencies]
cypherlite-query = "1.2"

use cypherlite_query::CypherLite;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = CypherLite::open("my_graph.cyl")?;

    // Create nodes and a relationship
    db.execute("CREATE (a:Person {name: 'Alice', age: 30})")?;
    db.execute("CREATE (b:Person {name: 'Bob', age: 25})")?;
    db.execute(
        "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) \
         CREATE (a)-[:KNOWS {since: 2023}]->(b)",
    )?;

    // Query the graph
    let result = db.execute("MATCH (p:Person) WHERE p.age > 20 RETURN p.name, p.age")?;
    for row in result {
        let row = row?;
        println!("{}: {}", row.get("p.name").unwrap(), row.get("p.age").unwrap());
    }
    Ok(())
}

Python

pip install cypherlite

import cypherlite

db = cypherlite.open("my_graph.cyl")

db.execute("CREATE (a:Person {name: 'Alice', age: 30})")
db.execute("CREATE (b:Person {name: 'Bob', age: 25})")
db.execute(
    "MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'}) "
    "CREATE (a)-[:KNOWS {since: 2023}]->(b)"
)

result = db.execute("MATCH (n:Person) RETURN n.name, n.age")
for row in result:
    print(f"{row['n.name']} (age: {row['n.age']})")

db.close()

Go

go get github.com/Epsilondelta-ai/CypherLite/bindings/go/cypherlite

package main

import (
    "fmt"
    "github.com/Epsilondelta-ai/CypherLite/bindings/go/cypherlite"
)

func main() {
    db, _ := cypherlite.Open("my_graph.cyl")
    defer db.Close()

    db.Execute("CREATE (a:Person {name: 'Alice', age: 30})")
    db.Execute("CREATE (b:Person {name: 'Bob', age: 25})")

    result, _ := db.Execute("MATCH (n:Person) RETURN n.name, n.age")
    for result.Next() {
        row := result.Row()
        name, _ := row.GetString("n.name")
        age, _ := row.GetInt64("n.age")
        fmt.Printf("%s (age: %d)\n", name, age)
    }
}

Node.js

npm install cypherlite

const { open } = require("cypherlite");

const db = open("my_graph.cyl");

db.execute("CREATE (a:Person {name: 'Alice', age: 30})");
db.execute("CREATE (b:Person {name: 'Bob', age: 25})");

const result = db.execute("MATCH (n:Person) RETURN n.name, n.age");
for (const row of result) {
  console.log(`${row["n.name"]} (age: ${row["n.age"]})`);
}

db.close();

Installation

Rust (Cargo)

[dependencies]
cypherlite-query = "1.2"

# Optional: enable specific feature flags
# cypherlite-query = { version = "1.2", features = ["temporal-edge", "plugin"] }

Python (pip)

pip install cypherlite

Build from source with full features:

cd crates/cypherlite-python
pip install maturin
maturin develop --release

Go (go get)

go get github.com/Epsilondelta-ai/CypherLite/bindings/go/cypherlite

Requires: Go 1.21+, Rust toolchain (to build the C static library), and a C compiler for CGo.

Node.js (npm)

npm install cypherlite

Build from source:

cd crates/cypherlite-node
npx napi build --release

Requires: Node.js 18+ with N-API v9 support and the Rust toolchain.

C (header + static library)

cargo build -p cypherlite-ffi --release --all-features

Link target/release/libcypherlite_ffi.a and include the generated cypherlite.h header.

Architecture

┌─────────────────────────────────────────┐
│           Application Layer             │
│  (user code: Rust, Python, Go, Node.js) │
├─────────────────────────────────────────┤
│     cypherlite-ffi / Bindings           │
│     (C ABI, PyO3, CGo, napi-rs)         │
├─────────────────────────────────────────┤
│         cypherlite-query                │
│  (Lexer → Parser → Planner → Executor)  │
├─────────────────────────────────────────┤
│        cypherlite-storage               │
│   (WAL, B+Tree, BufferPool, MVCC)       │
├─────────────────────────────────────────┤
│         cypherlite-core                 │
│   (Types, Traits, Error Handling)       │
└─────────────────────────────────────────┘
         ┊ plugin (orthogonal) ┊

Crate dependency graph:

cypherlite-query
    └── cypherlite-storage
            └── cypherlite-core

cypherlite-ffi
    └── cypherlite-query

cypherlite-python  (wraps cypherlite-ffi via PyO3)
cypherlite-node    (wraps cypherlite-ffi via napi-rs)

Query execution pipeline:

Cypher string
    → Lexer (logos tokenizer)
    → Parser (recursive descent + Pratt)
    → Semantic Analyzer (scope, labels)
    → Planner (logical → physical, cost-based)
    → Executor (Volcano iterator model)
    → QueryResult (iterable rows)

Feature Flags

Feature flags are additive. Each flag enables the features of all flags listed above it in the table, except plugin which is independent.

Flag Default Description
temporal-core Yes Core temporal features (AT TIME queries, version store)
temporal-edge No Temporal edge versioning and temporal relationship queries
subgraph No Subgraph entities (CREATE / MATCH SNAPSHOT)
hypergraph No Native N:M hyperedges (HYPEREDGE syntax); implies subgraph
full-temporal No All temporal features combined
plugin No Plugin system — 4 plugin types, zero overhead when disabled

Enable flags in Cargo.toml:

cypherlite-query = { version = "1.2", features = ["hypergraph", "plugin"] }

Performance

Benchmarks run with Criterion on an Apple M2 (single-threaded, in-memory WAL flush disabled):

Operation Throughput
Node INSERT ~180,000 ops/sec
Node LOOKUP by ID ~950,000 ops/sec
Edge INSERT ~160,000 ops/sec
Simple MATCH query ~120,000 queries/sec
WAL write throughput ~450 MB/sec

Run benchmarks locally:

cargo bench --workspace --all-features

Testing

# All tests (default features)
cargo test --workspace

# All tests with all features
cargo test --workspace --all-features

# Coverage report
cargo llvm-cov --workspace --all-features --summary-only

# Linter (zero warnings enforced)
cargo clippy --workspace --all-targets --all-features -- -D warnings

# Benchmark smoke test
cargo bench --workspace --all-features -- --test

Test suite: ~1,490 tests across workspace, all features enabled, 0 clippy warnings, 85%+ coverage.

Documentation

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for:

  • Bug reporting guidelines
  • Branch naming and pull request process
  • Development setup (Rust 1.84+)
  • Code style: cargo fmt, cargo clippy -- -D warnings
  • Test requirements: 85%+ coverage per commit

Open an issue first for significant changes to discuss the approach before implementation.

License

Licensed under either of:

at your option.

Status / Roadmap

Phase Version Feature Status
1 v0.1 Storage Engine (WAL, B+Tree, ACID) Complete
2 v0.2 Query Engine (Cypher lexer, parser, executor) Complete
3 v0.3 Advanced Query (MERGE, WITH, ORDER BY, optimizer) Complete
4 v0.4 Temporal Core (AT TIME, version store) Complete
5 v0.5 Temporal Edge (edge versioning) Complete
6 v0.6 Subgraph Entities (SubgraphStore, SNAPSHOT) Complete
7 v0.7 Native Hyperedge (N:M, HYPEREDGE syntax) Complete
8 v0.8 Inline Property Filter (pattern fix) Complete
9 v0.9 CI/CD Pipeline (GitHub Actions, 6 jobs) Complete
10 v1.0 Plugin System (4 plugin types, registry) Complete
11 v1.1 Performance Optimization (benchmarks, buffer pool) Complete
12 v1.1 FFI Bindings (C, Python, Go, Node.js) Complete
13 v1.2 Documentation & i18n (rustdoc, website, examples) Current