GraphQLite Rust

Rust bindings for GraphQLite, a SQLite extension that adds graph database capabilities using Cypher.

Installation

Add to your Cargo.toml:

[dependencies]
graphqlite = "0.1.0-beta"

Quick Start

High-Level Graph API (Recommended)

The Graph struct provides an ergonomic interface for common graph operations:

use graphqlite::Graph;

fn main() -> graphqlite::Result<()> {
    let g = Graph::open(":memory:")?;

    // Add nodes
    g.upsert_node("alice", [("name", "Alice"), ("age", "30")], "Person")?;
    g.upsert_node("bob", [("name", "Bob"), ("age", "25")], "Person")?;

    // Add edge
    g.upsert_edge("alice", "bob", [("since", "2020")], "KNOWS")?;

    // Query
    println!("{:?}", g.stats()?);           // GraphStats { nodes: 2, edges: 1 }
    println!("{:?}", g.get_neighbors("alice")?);

    // Graph algorithms
    let ranks = g.pagerank(0.85, 20)?;
    let communities = g.community_detection(10)?;

    Ok(())
}

Low-Level Cypher API

For complex queries or when you need full control:

use graphqlite::Connection;

fn main() -> graphqlite::Result<()> {
    let conn = Connection::open("graph.db")?;

    conn.cypher("CREATE (a:Person {name: 'Alice', age: 30})")?;
    conn.cypher("CREATE (b:Person {name: 'Bob', age: 25})")?;
    conn.cypher(r#"
        MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
        CREATE (a)-[:KNOWS]->(b)
    "#)?;

    let results = conn.cypher("MATCH (a:Person)-[:KNOWS]->(b) RETURN a.name, b.name")?;
    for row in &results {
        let a: String = row.get("a.name")?;
        let b: String = row.get("b.name")?;
        println!("{} knows {}", a, b);
    }

    Ok(())
}

API Reference

Graph

use graphqlite::{Graph, graph};

// Constructor
let g = Graph::open("graph.db")?;
let g = Graph::open(":memory:")?;
let g = Graph::open_in_memory()?;

// Or use the factory function
let g = graph(":memory:")?;

Node Operations

Edge Operations

Graph Queries

Graph Algorithms

Centrality

Community Detection

Connected Components

Path Finding

Traversal

Similarity

Batch Operations

// Batch insert nodes (upsert semantics)
g.upsert_nodes_batch([
    ("n1", [("name", "Node1")], "Type"),
    ("n2", [("name", "Node2")], "Type"),
])?;

// Batch insert edges (upsert semantics)
g.upsert_edges_batch([
    ("n1", "n2", [("weight", "1.0")], "CONNECTS"),
])?;

Bulk Insert (High Performance)

For maximum throughput when building graphs from external data, use the bulk insert methods. These bypass Cypher parsing entirely and use direct SQL, achieving 100-500x faster insert rates.

// Bulk insert nodes - returns HashMap<external_id, internal_rowid>
let id_map = g.insert_nodes_bulk([
    ("alice", vec![("name", "Alice"), ("age", "30")], "Person"),
    ("bob", vec![("name", "Bob"), ("age", "25")], "Person"),
    ("charlie", vec![("name", "Charlie")], "Person"),
])?;

// Bulk insert edges using the ID map - no MATCH queries needed!
let edges_inserted = g.insert_edges_bulk(
    [
        ("alice", "bob", vec![("since", "2020")], "KNOWS"),
        ("bob", "charlie", vec![("since", "2021")], "KNOWS"),
    ],
    &id_map,
)?;

// Or use the convenience method for both
let result = g.insert_graph_bulk(nodes, edges)?;
println!("Inserted {} nodes, {} edges", result.nodes_inserted, result.edges_inserted);

// Resolve existing node IDs (for edges to pre-existing nodes)
let resolved = g.resolve_node_ids(["alice", "bob"])?;

Connection

use graphqlite::Connection;

let conn = Connection::open("graph.db")?;
let conn = Connection::open(":memory:")?;
let conn = Connection::open_in_memory()?;

// Wrap existing rusqlite connection
let sqlite_conn = rusqlite::Connection::open_in_memory()?;
let conn = Connection::from_rusqlite(sqlite_conn)?;

Methods

CypherResult

let results = conn.cypher("MATCH (n) RETURN n.name")?;

results.len();           // Number of rows
results.is_empty();      // Check if empty
results.columns();       // Column names
results[0];              // First row

for row in &results {
    let name: String = row.get("n.name")?;
}

Row

Type-safe value extraction:

let name: String = row.get("name")?;
let age: i64 = row.get("age")?;
let score: f64 = row.get("score")?;
let active: bool = row.get("active")?;
let maybe: Option<String> = row.get("optional")?;

Utility Functions

use graphqlite::{escape_string, sanitize_rel_type, CYPHER_RESERVED};

// Escape strings for Cypher queries
let safe = escape_string("it's");  // "it\\'s"

// Sanitize relationship types
let rel = sanitize_rel_type("has-items");  // "has_items"
let rel = sanitize_rel_type("CREATE");     // "REL_CREATE"

// Check reserved keywords
if CYPHER_RESERVED.contains(&"MATCH") {
    println!("MATCH is reserved");
}

Extension Path

The extension is located automatically. To specify a custom path:

let conn = Connection::open_with_extension("graph.db", "/path/to/graphqlite.dylib")?;

Or set the GRAPHQLITE_EXTENSION_PATH environment variable.

License

MIT