velesdb-core

The embedded tri-engine of VelesDB: vector, graph and columnar metadata in one Rust database.

Objective

Semantic retrieval usually means running a vector store, a graph database and a relational store side by side, then stitching their results together in application code — three deployments, three consistency stories, three query languages.

velesdb-core is the embedded engine that collapses those three into one process and one language. Vectors (HNSW + SIMD), typed graph edges and typed columnar metadata live in the same collection and are queried together with VelesQL. No server, no network hop, no external dependency: it is a Rust library that reads and writes a directory on your disk.

If you do not need retrieval over your own data, you do not need this crate.

Use cases

• A desktop or CLI application that must search its own documents offline, with no service to install and no data leaving the machine.
• A RAG pipeline that filters candidates on structured metadata (tenant, date, status) in the same query as the vector search, instead of post-filtering results and losing recall.
• A recommendation feature where "similar to this item" must be combined with "and connected to the user by at most 2 hops" — vector plus graph traversal in one statement.
• An AI agent that needs durable memory (facts, events, learned procedures) with TTL and snapshots, embedded in the agent process itself.
• An embedded/edge deployment where a 32x-compressed index must fit in RAM on constrained hardware.

Prerequisites

Installation

cargo add velesdb-core

For WASM or any target without a filesystem, disable the default feature:

cargo add velesdb-core --no-default-features

First success in 60 seconds

Create a project, add the two dependencies, paste this into src/main.rs, run it.

cargo new veles-hello && cd veles-hello
cargo add velesdb-core serde_json

use serde_json::json;
use velesdb_core::{Database, DistanceMetric, Point};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Open (or create) a local database directory.
    let db = Database::open("./veles-quickstart")?;

    // 2. One collection = one vector dimension + one distance metric (both immutable).
    db.create_collection("documents", 4, DistanceMetric::Cosine)?;
    let documents = db
        .get_vector_collection("documents")
        .ok_or("collection not found")?;

    // 3. Insert points: id, vector, optional JSON payload.
    documents.upsert(vec![
        Point::new(1, vec![1.0, 0.0, 0.0, 0.0], Some(json!({"title": "rust"}))),
        Point::new(2, vec![0.0, 1.0, 0.0, 0.0], Some(json!({"title": "python"}))),
        Point::new(3, vec![0.9, 0.1, 0.0, 0.0], Some(json!({"title": "cargo"}))),
    ])?;

    // 4. flush() is the explicit durability barrier.
    documents.flush()?;

    // 5. Search: top-2 nearest neighbours of [1, 0, 0, 0].
    for hit in documents.search(&[1.0, 0.0, 0.0, 0.0], 2)? {
        let title = hit
            .point
            .payload
            .as_ref()
            .and_then(|payload| payload.get("title"))
            .and_then(serde_json::Value::as_str)
            .unwrap_or("<none>");
        println!("id={} title={title} score={:.4}", hit.point.id, hit.score);
    }

    Ok(())
}

$ cargo run
id=1 title=rust score=1.0000
id=3 title=cargo score=0.9939

Success looks exactly like that: two lines, id=1 first with a cosine score of 1.0000 (the query vector is identical to point 1), id=3 second. Point 2 is orthogonal to the query and is correctly excluded from the top 2.

Anything else is a failure — in particular, a second cargo run prints Error: CollectionExists("documents") because the collection is already persisted in ./veles-quickstart. Delete that directory to start over, or skip create_collection when the collection already exists.

Configuration

Compile-time features (Cargo.toml):

Runtime settings (HNSW parameters, limits, storage, logging) are read from velesdb.toml — see the configuration guide.

Examples

• examples/ — crash_driver (crash-recovery test driver), profile_batch_insert (flamegraph target for HNSW batch insert), simd_precision_check (SIMD vs scalar validation). These are engine tooling, not tutorials.
• examples/rust/ — multimodel_search.rs, a runnable vector + graph + metadata query.
• examples/mini_recommender/ and examples/ecommerce_recommendation/ — complete standalone applications.

API / commands

Generated reference: docs.rs/velesdb-core. Import map (where each type lives): Core API map.

Task guides, all moved out of this README so it stays readable:

Performance

Two headline numbers, both measured rather than estimated. Every figure, its hardware and its reproduction command live in Core performance.

Reproduce with cargo bench -p velesdb-core --bench hnsw_benchmark and cargo bench -p velesdb-core --bench column_filter_benchmark.

Numbers move with hardware and dataset. Treat them as the shape of the engine's cost, not a guarantee for your workload — measure on yours.

Known limits

• No embedding generation. You bring the vectors; the crate never calls a model or the network to produce them.
• No clustering, sharding or replication. velesdb-core is a single-process embedded engine. One process at a time may open a database directory: a second one fails with DatabaseLocked.
• One writer per collection. Concurrent readers are fine; concurrent writers to the same collection serialize — see Write concurrency.
• Metric and dimension are immutable. Changing either means creating a new collection and reindexing.
• JOIN ... USING (...) supports one column only. Multi-column USING parses but does not execute; use JOIN ... ON left = right instead.
• No agent-memory service layer here. The explainable MemoryService, why() and the deterministic context compiler (compile_context) live one level up in velesdb-memory, which depends on this crate — never the reverse.
• WASM builds are read/compute only. --no-default-features removes mmap storage, WAL, rayon and tokio along with the persistence feature.

Compatibility

velesdb-core is a library, not an agent or MCP surface, so this table lists the platforms and toolchains the project builds and tests on.

Troubleshooting

License

VelesDB Core License 1.0 — see LICENSE.

Last updated: 2026-07-25 · Applies to: velesdb-core 5.0.0 · Report a docs error