Velr

Velr is an embedded property-graph database from Velr.ai, written in Rust, built on top of SQLite3 (persisting to a standard SQLite database file) and queried using the openCypher language.

This crate provides the Rust binding for Velr. It links against a bundled native runtime with a C ABI, implemented in Rust.

For the main Velr public entry point, see velr-ai/velr.
For the Velr website, see velr.ai.

Community

• Community and questions: GitHub Discussions
• Bug reports and feature requests: GitHub Issues
• Rust examples: velr-rust-examples

We’d love to have you join the Velr community.

---

Release status

This release is alpha.

• The Rust API is still evolving.
• Velr supports openCypher and passes all positive openCypher TCK tests. Exact error semantics are not guaranteed to match other openCypher implementations.
• Velr 0.2.14 includes a breaking on-disk storage change; existing databases from earlier releases must be recreated by re-importing the source data.
• Starting with the 0.3.x series, we intend to guarantee internal database compatibility within the branch.

Schema version 7 compatibility

This release's current on-disk schema is version 7. Supported older databases can be opened with Velr::open or Velr::open_readonly without changing the file. Reads continue to work on those databases, but writes (CREATE, MERGE, SET, DELETE, DETACH DELETE, and other mutating queries) are only available after migrating to the current schema version. This is intentional: migration is an explicit maintenance operation, not a side effect of opening a database.

Velr is already usable for real workflows and representative use cases, but rough edges remain and the API is not yet stable.

Fulltext search and vector search are available today through Cypher DDL and CALL syntax. API details may still evolve while Velr remains alpha.

---

Installation

Add to Cargo.toml:

[dependencies]
velr = "0.2"

Arrow IPC support is enabled by default. To build without Arrow IPC support, opt out of default features:

[dependencies]
velr = { version = "0.2", default-features = false }

---

Quick start

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

---

Opening an existing database read-only

Use Velr::open_readonly(path) for viewers, agents, and other read paths that should not initialize or migrate the database:

use velr::Velr;

fn main() -> velr::Result<()> {
    let db = Velr::open_readonly("mygraph.db")?;
    let mut table = db.exec_one("MATCH (n) RETURN count(n) AS count")?;

    table.for_each_row(|row| {
        println!("{:?}", row[0]);
        Ok(())
    })?;

    Ok(())
}

open_readonly requires an existing file-backed database at a supported Velr schema version. It does not create files, run schema DDL, or migrate older databases. Older supported databases, such as schema version 3, 4, 5, or 6 databases opened by a schema version 7 runtime, remain available for reads. Writes and features that require the current schema fail with a normal query error until the database is explicitly migrated.

---

Schema migration

Velr does not migrate supported older databases automatically on open. Use the driver migration API, or run MIGRATE DATABASE, from maintenance code when you intend to update the on-disk schema. See the release-status note above for the schema version 7 read/write compatibility behavior.

use velr::{MigrationStatus, Velr};

fn main() -> velr::Result<()> {
    let db = Velr::open(Some("mygraph.db"))?;

    if db.needs_migration()? {
        let report = db.migrate()?;
        match report.status {
            MigrationStatus::Migrated => {
                println!(
                    "migrated schema {} -> {} via {:?}",
                    report.from_version, report.to_version, report.steps
                );
            }
            MigrationStatus::AlreadyCurrent => {}
        }
    }

    Ok(())
}

The equivalent Cypher command is useful for scripts and tools that already work through query execution:

let db = Velr::open(Some("mygraph.db"))?;
let mut report = db.exec_one("MIGRATE DATABASE")?;
println!("{:?}", report.column_names());

---

Introspection

Use SHOW CURRENT GRAPH SHAPE to inspect the observed schema of the graph. It reports the shape present in stored data: node labels, relationship types, properties, observed value types, and counts. It is an observed shape surface, not a declared GQL graph type.

SHOW CURRENT GRAPH SHAPE is available on schema version 5 or newer databases. Older supported databases can still be opened for reads, but must be migrated explicitly before this command is valid. Schema version 5 introduced this inventory through the write planner instead of persistent graph-shape triggers.

The default projection returns element_kind, element_name, property_name, observed_type, owner_count, present_count, and missing_count. YIELD * exposes the full row shape, including surface, source_label, target_label, required, storage_class, and tag.

let db = Velr::open(Some("mygraph.db"))?;

let mut shape = db.exec_one(
    "SHOW CURRENT GRAPH SHAPE
     YIELD element_kind, element_name, property_name, observed_type, owner_count
     WHERE element_kind = 'node_property'
     RETURN element_name, property_name, observed_type, owner_count",
)?;

shape.for_each_row(|row| {
    println!("{row:?}");
    Ok(())
})?;

Use YIELD to compose the command with WHERE and RETURN. Plain SHOW CURRENT GRAPH SHAPE returns the default projection; YIELD * exposes the full current row shape.

---

Fulltext Search

Fulltext search is available through normal Cypher execution. Define indexes with CREATE FULLTEXT INDEX and query them with CALL db.index.fulltext.queryNodes(...).

let db = Velr::open(Some("mygraph.db"))?;

db.run(
    "CREATE FULLTEXT INDEX paperText
     FOR (n:Paper) ON EACH [n.title, n.abstract]",
)?;

let mut rows = db.exec_one(
    "CALL db.index.fulltext.queryNodes('paperText', 'abstract:vector')
     YIELD node, score
     RETURN node, score",
)?;

The query string supports this fulltext grammar:

• Terms: vector search
• Phrases: "vector search"
• Field scoping by indexed property: title:graph, abstract:"vector search"
• Boolean operators and grouping: graph AND (vector OR semantic)
• Default OR between adjacent terms: vector search
• Required and excluded terms: +vector -draft
• Phrase slop: "vector search"~2
• Phrase prefix on the last phrase term: "vector sea"*
• Boosts: title:graph^2.0
• Match all indexed nodes: *

Field scoping applies to the next term or phrase only. For example, title:graph search searches graph in title and search in the default fulltext field.

score is a non-normalized relevance score. Higher scores are better within a single query result set; scores are not guaranteed to be in 0..1 or comparable across different queries.

Fulltext indexes use a sidecar next to file-backed databases. The sidecar is kept up to date by writes and rebuilt on open if it is missing or corrupt.

---

Vector Search

Register an embedding callback, then reference it from CREATE VECTOR INDEX. Velr invokes the callback for index maintenance when indexed source values change and for text queries passed to CALL db.index.vector.queryNodes(...).

use velr::{PropertyValue, VectorEmbeddingPurpose, Velr};

fn embed_text(_text: &str, dimensions: usize) -> Vec<f32> {
    // Call your embedding model here.
    vec![0.0; dimensions]
}

fn main() -> velr::Result<()> {
    let db = Velr::open(Some("mygraph.db"))?;

    db.register_vector_embedder("text", |inputs| {
        Ok(inputs
            .iter()
            .map(|input| {
                let text = input
                    .fields
                    .iter()
                    .filter_map(|field| match &field.value {
                        PropertyValue::String(value) => Some(value.as_str()),
                        _ => None,
                    })
                    .collect::<Vec<_>>()
                    .join("\n");

                let prefix = match input.purpose {
                    VectorEmbeddingPurpose::IndexEntity => "passage: ",
                    VectorEmbeddingPurpose::Query => "query: ",
                };
                embed_text(&format!("{prefix}{text}"), input.dimensions)
            })
            .collect())
    })?;

    db.run(
        "CREATE VECTOR INDEX paperEmbedding IF NOT EXISTS
         FOR (n:Paper)
         ON EACH [n.title, n.abstract]
         OPTIONS { indexConfig: { dimensions: 384, metric: 'cosine', embedder: 'text' } }",
    )?;

    let mut _rows = db.exec_one(
        "CALL db.index.vector.queryNodes('paperEmbedding', 10, 'paper about greek letters')
         YIELD node, score
         RETURN node, score",
    )?;

    Ok(())
}

ON EACH [n.title, n.abstract] passes both property values to the callback in that order. Query text is passed as one unnamed string field. Vector score is metric-dependent and non-normalized; higher scores are better within a single query result set.

---

Query language support

Velr supports the openCypher query language and passes all positive openCypher TCK tests. Exact error semantics, including error messages, categories, and timing, are not guaranteed to match other openCypher implementations.

---

Streaming multiple result tables

A single exec() can yield multiple result tables (e.g. multiple statements):

let db = Velr::open(None)?;
let mut stream = db.exec(
    "MATCH (m:Movie {title:'The Matrix'}) RETURN m.title AS title;
     MATCH (m:Movie {title:'Inception'})  RETURN m.released AS year"
)?;

while let Some(mut table) = stream.next_table()? {
    println!("{:?}", table.column_names());
    table.for_each_row(|row| {
        println!("{row:?}");
        Ok(())
    })?;
}

---

Bounded result previews

Use QueryOptions::max_result_rows when a host needs projected column names and a small row sample without rewriting the Cypher text:

use velr::{QueryOptions, Velr};

fn main() -> velr::Result<()> {
    let db = Velr::open_readonly("mygraph.db")?;
    let mut table = db.exec_one_with_options(
        "MATCH (n) RETURN labels(n) AS labels, n.name AS name ORDER BY name",
        QueryOptions::max_result_rows(20),
    )?;

    let columns = table.column_names().to_vec();
    let sample = table.collect(|row| {
        Ok(row.iter().map(|cell| format!("{cell:?}")).collect::<Vec<_>>())
    })?;

    println!("{columns:?}");
    println!("{sample:?}");
    Ok(())
}

max_result_rows = 0 preserves the returned column metadata and opens row cursors at EOF. The cap is enforced by Velr during result emission, not by appending or injecting Cypher LIMIT, and applies independently to each result table produced by exec_with_options. Existing Cypher LIMIT clauses still apply, so a query with LIMIT 3 and max_result_rows = 5 emits at most three rows, while LIMIT 10 with max_result_rows = 5 emits at most five rows. It is not a timeout or cancellation mechanism; hosts that need read-only validation or execution deadlines should keep those checks separate.

Query parameter binding

Use params!, QueryParams, or QueryOptions::with_param to bind openCypher parameters out of band. Query text uses $name; API parameter names omit the leading $. Values are passed as Cypher values, not interpolated into query text, so a Rust String is always a Cypher string value.

use velr::{QueryOptions, Velr};

fn main() -> velr::Result<()> {
    let db = Velr::open(None)?;

    db.run_with_params(
        "CREATE (:Person {name: $name, age: $age})",
        velr::params! {
            name: "Alice",
            age: 42_i64,
        }?,
    )?;

    let mut table = db.exec_one_with_options(
        "MATCH (p:Person) WHERE p.age >= $min_age RETURN p.name AS name ORDER BY name",
        QueryOptions::max_result_rows(20).with_param("min_age", 18_i64)?,
    )?;

    println!("{:?}", table.column_names());
    table.for_each_row(|row| {
        println!("{row:?}");
        Ok(())
    })?;
    Ok(())
}

Supported parameter values are null, booleans, signed 64-bit integers, finite floats, strings, lists, and maps. Lists and maps can be supplied as QueryValue::List / QueryValue::Map, Rust Vecs, BTreeMap<String, _>, HashMap<String, _>, or serde_json::Value.

Use string-literal keys in params! for parameter names that are not Rust identifiers, such as $1: velr::params! { name: "Alice", "1" => 42_i64 }?.

---

Transactions and savepoints

Velr supports transactions together with two kinds of savepoints:

• Scoped savepoints via savepoint(), which return a guard
• Named savepoints via savepoint_named(name), which remain active in the transaction until released or the transaction ends

Calling rollback_to(name) rolls back to the named savepoint, discards any newer named savepoints, and keeps the target savepoint active.

Scoped savepoint

let db = Velr::open(None)?;

let tx = db.begin_tx()?;
tx.run("CREATE (:Temp {k:'outer'})")?;

{
    let sp = tx.savepoint()?;
    tx.run("CREATE (:Temp {k:'inner'})")?;
    sp.rollback()?; // rollback to the scoped savepoint
}

tx.commit()?;

Named savepoints

let db = Velr::open(None)?;

let tx = db.begin_tx()?;

tx.savepoint_named("before_write1")?;
tx.run("CREATE (:Temp {k:'a'})")?;

tx.savepoint_named("before_write2")?;
tx.run("CREATE (:Temp {k:'b'})")?;

tx.rollback_to("before_write1")?;
tx.run("CREATE (:Temp {k:'c'})")?;

tx.release_savepoint("before_write1")?;
tx.commit()?;

release_savepoint(name) currently releases the most recent active named savepoint.

Dropping an active transaction without commit() will roll it back automatically.

---

Explain plans

Velr can produce an explain trace for a query, which is useful when you want to inspect how a openCypher query is planned and translated internally.

Use Velr::explain to build a trace without executing the query:

use velr::Velr;

fn main() -> velr::Result<()> {
    let db = Velr::open(None)?;

    let trace = db.explain("MATCH (n) RETURN n")?;

    println!("plans: {}", trace.plan_count()?);
    println!("{}", trace.to_compact_string()?);

    Ok(())
}

The returned ExplainTrace can be inspected programmatically or rendered as a compact string for logging, debugging, tests, or documentation.

---

Arrow IPC

Arrow IPC support is enabled by default. With the default feature set you can:

• Bind Arrow arrays as a logical table (bind_arrow, bind_arrow_chunks)
• Bind Arrow IPC file / Feather v2 bytes as a logical table (bind_arrow_ipc)
• Export a result table as an Arrow IPC file (to_arrow_ipc_file())

#[cfg(feature = "arrow-ipc")]
fn arrow_example() -> velr::Result<()> {
    use arrow2::array::{Array, Utf8Array};

    let db = Velr::open(None)?;

    let cols = vec!["name".to_string()];
    let arrays: Vec<Box<dyn Array>> = vec![
        Utf8Array::<i64>::from(vec![Some("Alice"), Some("Bob")]).boxed(),
    ];

    db.bind_arrow("_people", cols, arrays)?;
    db.run("UNWIND BIND('_people') AS r CREATE (:Person {name:r.name})")?;

    let mut t = db.exec_one("MATCH (p:Person) RETURN p.name AS name ORDER BY name")?;
    let ipc = t.to_arrow_ipc_file()?;

    println!("IPC bytes: {}", ipc.len());
    Ok(())
}

---

OpenCypher functions

The following openCypher functions and constructors are available:

Graph and path

• id()
• type()
• labels()
• keys()
• properties()
• length()
• nodes()
• relationships()

Lists and predicates

• size()
• head()
• last()
• tail()
• reverse()
• range()
• all()
• any()
• none()
• single()

Strings and conversion

• coalesce()
• toInteger()
• toString()
• toLower()
• trim()
• substring()
• split()

Numeric

• abs()
• ceil()
• rand()
• sign()
• sqrt()

Temporal

• date()
• time()
• localtime()
• datetime()
• localdatetime()
• duration()
• datetime.fromepoch()
• datetime.fromepochmillis()
• date.realtime(), date.transaction(), date.statement()
• time.realtime(), time.transaction(), time.statement()
• localtime.realtime(), localtime.transaction(), localtime.statement()
• datetime.realtime(), datetime.transaction(), datetime.statement()
• localdatetime.realtime(), localdatetime.transaction(), localdatetime.statement()

Aggregates

• count()
• sum()
• avg()
• min()
• max()
• collect()
• percentileDisc()
• percentileCont()

---

Platform support

This crate links against a bundled native runtime. Cargo selects one platform-specific velr-runtime-* crate for the current build target, so user installation stays:

[dependencies]
velr = "0.2"

Currently bundled targets:

• macOS universal (arm64 + x86_64)
• Linux x86_64
• Linux aarch64
• Windows x86_64

---

Licensing

• The Rust binding source code in this package is licensed under MIT.
• The bundled native runtime binaries may be used and freely redistributed in unmodified form under the terms of LICENSE.runtime.

See LICENSE and LICENSE.runtime for the full license texts.