Skip to content

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

Velr is currently in public alpha and is released under a Free Binary Redistribution License.

Note

Velr 1.0 is focused on strong openCypher compatibility.
Vector search, time-series, and federation are planned as post-1.0 capabilities.

Getting Velr

Velr is available today as a Rust crate and a Python package.

The Velr CLI is not yet available for download, but it will be available soon.

For more complete end-to-end examples, real workflows, and usage patterns, see the dedicated example repositories:

Shell (CLI)

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

Status: coming soon.

Once available, you will be able to start an in-memory session:

velr
````

Or open a file-backed database:

```bash
velr movies.db

Example interactive session:

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.

For comprehensive Python examples and workflows, see:

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:

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'})")

The velr-python-examples repository contains more comprehensive examples for working with Velr in Python.

Rust crate (Cargo)

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

For comprehensive Rust examples and workflows, see:

Add Velr to your Cargo.toml:

[dependencies]
velr = "0.2"

A minimal example:

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(())
}

The velr-rust-examples repository contains more comprehensive examples for working with Velr in Rust.

Community

Questions, feedback, and ideas are welcome.