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 openCypher graphs, SQL, vectors, and time-series on top of SQLite, with a tiny footprint and seamless integration into Python and Rust applications.

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.

To install you need to need beta access. 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)¶

Velr is available on PyPI.

Velr currently requires Python 3.12 or newer.

Using a Python virtual environment is recommended:

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

For Arrow / dataframe workflows, install the optional dependencies you want to use:

```bash
pip install pyarrow pandas polars

A minimal example:

from velr.driver import Velr

MOVIES_CREATE = r"""
CREATE
  (keanu:Person:Actor {name:'Keanu Reeves', born:1964}),
  (nolan:Person:Director {name:'Christopher Nolan'}),
  (matrix:Movie {title:'The Matrix', released:1999, genres:['Sci-Fi','Action']}),
  (inception:Movie {title:'Inception', released:2010, genres:['Sci-Fi','Heist']}),
  (keanu)-[:ACTED_IN {roles:['Neo']}]->(matrix),
  (nolan)-[:DIRECTED]->(inception);
"""

with Velr.open(None) as db:
    db.run(MOVIES_CREATE)

    with db.exec_one(
        "MATCH (m:Movie {title:'Inception'}) "
        "RETURN m.title AS title, m.released AS year, m.genres AS genres"
    ) as table:
        print(table.column_names())

        with table.rows() as rows:
            row = next(rows)

    title, year, genres = row
    print(title.as_python())
    print(year.as_python())
    print(genres.as_python())

Open a file-backed database instead of an in-memory database:

from velr.driver import Velr

with Velr.open("mygraph.db") as db:
    db.run("CREATE (:Person {name:'Alice'})")

Rust crate (Cargo)¶

Velr is available as a Rust crate on crates.io, with API documentation on docs.rs and source code on GitHub.

Add Velr to your Cargo.toml:

[dependencies]
velr = "0.1"
````

A minimal example:

```rust
use velr::{Velr, CellRef};

fn main() -> velr::Result<()> {
    // Open in-memory DB (pass Some("path.db") for file-backed)
    let db = Velr::open(None)?;

    db.run("CREATE (:Person {name:'Keanu Reeves', born:1964})")?;

    let mut t = db.exec_one("MATCH (p:Person) RETURN p.name AS name, p.born AS born")?;

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

    t.for_each_row(|row| {
        match row[0] {
            CellRef::Text(bytes) => println!("name={}", std::str::from_utf8(bytes).unwrap()),
            _ => {}
        }
        match row[1] {
            CellRef::Integer(i) => println!("born={i}"),
            _ => {}
        }
        Ok(())
    })?;

    Ok(())
}