Get Started¶

Velr is a lightweight embedded graph database written in Rust, designed for edge systems, agent memory, and modern data-science workflows. It unifies Cypher graphs, SQL, vectors, and time-series on top of SQLite, with a tiny footprint and seamless integration into Python and Rust applications.

Note

During the beta period, Velr is invite-only. If you’d like to try it, please email tomas@velr.ai

Installation¶

Velr provides a Rust crate, a Python driver, an interactive shell, and optional Jupyter integration.

Shell (CLI)¶

The Velr shell is handy for ad-hoc queries, quick experiments, and scripting.

Install it either via pip or Cargo:

# via pip
pip install velr-shell

# via Cargo
cargo install velr-shell

Once installed, start an in-memory session:

velr

Or open a file-backed database:

velr movies.db

velr> CREATE (:Movie {title:'Inception', released:2010});
velr> MATCH (m:Movie) RETURN m.title as title, m.released as year;
+-----------+----------+
| title     | year     |
+-----------+----------+
| Inception | 2010     |
+-----------+----------+

Python Driver (pip)¶

Using a Python virtual environment is recommended. Open a terminal and install Velr inside a virtual environment:

python3 -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install velr

Once installed, you can open an in-memory Velr database and run Cypher queries directly from Python:

# hello_velr.py
from velrpy.driver import Velr

def main():
    with Velr.open(None) as db:
        # Create a tiny graph
        db.run("CREATE (:Movie {title:'Inception', released:2010});")

        # Query it and show the result as a DataFrame
        with db.exec_one(
            "MATCH (m:Movie {title:'Inception'}) "
            "RETURN m.title AS title, m.released AS year"
        ) as table:
            print(table.to_pandas())

if __name__ == "__main__":
    main()

Rust crate (Cargo)¶

Add Velr to your Cargo.toml:

[dependencies]
velr = "0.1"

A minimal in-memory example:

// src/main.rs
use velr::{Velr, CellRef};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // In-memory database
    let db = Velr::open(None)?;

    // Create a tiny graph
    db.run("CREATE (:Movie {title:'Inception', released:2010});")?;

    // Query it back
    let mut table = db.exec_one(
        "MATCH (m:Movie {title:'Inception'}) \
         RETURN m.title AS title, m.released AS year",
    )?;

    println!("{:?}", table.column_names());

    table.for_each_row(|row| {
        let title = match row[0] {
            CellRef::Text(bytes) => std::str::from_utf8(bytes).unwrap_or("<utf8>"),
            _ => "<non-text>",
        };
        let year = match row[1] {
            CellRef::Integer(y) => y,
            _ => 0,
        };
        println!("{title} ({year})");
        Ok(())
    })?;

    Ok(())
}