kglite

Pure-Rust knowledge graph engine — Cypher pipeline, snapshot/working CoW transactions, columnar / mmap / disk storage backends, optional dataset loaders (SEC EDGAR, Sodir, Wikidata). Zero PyO3 in the dependency tree; embed directly from any Rust binary.

Looking for the Python wheel? pip install kglite — the wheel is a separate PyO3 wrapper (kglite-py) built on top of this crate. See the workspace README for the Python story; this page is the crates.io-side documentation.

Quick start

[dependencies]
kglite = "0.10"

use kglite::api::{load_file, session, Value};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load any .kgl file — same format the Python wheel writes.
    let graph = load_file("graph.kgl")?;

    let params = HashMap::new();
    let opts = session::ExecuteOptions {
        params: &params,
        deadline: None,
        max_rows: None,
        lazy_eligible: false,
        disabled_passes: None,
        embedder: None,
    };
    let outcome = session::execute_read(
        &graph,
        "MATCH (n:Person) RETURN n.name LIMIT 10",
        &opts,
    )?;

    for row in &outcome.result.rows {
        if let Some(Value::String(name)) = row.first() {
            println!("{}", name);
        }
    }
    Ok(())
}

Verify no Python dep leaked in:

cargo tree -p your-crate | grep pyo3   # → (empty)

What's in it

Transactions

The Session / Transaction types wrap the snapshot/working CoW

• optimistic concurrency control. Pattern: begin, mutate, commit. On a concurrent-writer conflict, the second commit returns CommitOutcome::ConflictDetected and the binding surfaces it to its caller as a retryable error.

use kglite::api::session::{CommitOutcome, ExecuteOptions, Session};
use kglite::api::DirGraph;
use std::collections::HashMap;
use std::sync::Arc;

let session = Arc::new(Session::new(DirGraph::new()));
let params: HashMap<String, kglite::api::Value> = HashMap::new();
let opts = ExecuteOptions {
    params: &params, deadline: None, max_rows: None,
    lazy_eligible: false, disabled_passes: None, embedder: None,
};

let mut tx = session.begin();
kglite::api::session::execute_mut(
    tx.working_mut()?,
    "CREATE (:Person {id: 1, name: 'Alice'})",
    &opts,
)?;

match session.commit(tx, /* check_occ = */ true) {
    CommitOutcome::Committed { new_version } => {
        println!("committed at version {}", new_version);
    }
    CommitOutcome::ConflictDetected { current_version, base_version } => {
        eprintln!("conflict: base={} current={}", base_version, current_version);
    }
    CommitOutcome::NoWritesNoOp => {}
}

Examples

Three runnable examples ship with the crate:

cargo run --example embedded_basic -- graph.kgl
cargo run --example embedded_session
cargo run --example embedded_blueprint

• embedded_basic — load + query. Smallest embedder.
• embedded_session — two concurrent transactions; OCC catches the conflict.
• embedded_blueprint — parse the kglite source tree itself, query the resulting graph.

Feature flags

Polars-io style: opt in only to what you use.

[dependencies]
kglite = { version = "0.10", features = ["sec", "sodir"] }

Documentation

• Rust quickstart — load + query + transaction examples.
• Embedding guide — workspace layout, the kglite::api::* surface tour, sketches for cgo / napi / JNI wrappers if you're building a binding in another language.
• Session abstraction — binding-implementer reference for the canonical Cypher pipeline
  • CoW transaction model.
• API manifest — curated inventory of kglite::api::* items + semver rules.
• Per-symbol docs at docs.rs/kglite.

The full kglite docs site at kglite.readthedocs.io has more on the Cypher subset, design rationale, and the protocol-server binaries that ship alongside this crate.

Semver

kglite::api::* items get semver guarantees within a minor release. Anything outside that surface — kglite::graph::*, kglite::datatypes::*, raw module paths — is internal and may move freely between minor releases.

License

MIT — see LICENSE.