How VelesDB Unifies Vector Search, Graph Databases, and Column Stores

VelesDB unifies vector search, graph databases, and column stores through a single VelesQL engine that aggregates a VectorStore, GraphStore, and ColumnStore within each collection, enabling hybrid queries across all three data models in one SQL-like syntax.

VelesDB is an open-source multimodal database from cyberlife-coder/velesdb designed to eliminate data silos between AI embeddings, knowledge graphs, and structured analytics. By co-locating HNSW vector indices, graph traversals, and columnar storage inside a single collection, VelesDB answers how it unifies vector search, graph databases, and column stores through a shared execution engine and the VelesQL query language.

The Three-Store Architecture

Every VelesDB collection aggregates three specialized storage engines defined in crates/velesdb-core/src/collection/types.rs. This design allows vectors, graph edges, and structured metadata to coexist as first-class citizens.

VectorStore and Native HNSW Indexing

Raw embedding vectors live in a contiguous VectorStore (crates/velesdb-core/src/index/hnsw/vector_store.rs). This store feeds a native HNSW index implemented in crates/velesdb-core/src/index/hnsw/native_index.rs as NativeHnswIndex. The index provides sub-millisecond approximate-nearest-neighbour (ANN) queries with the search method, returning candidate IDs that the execution engine can route to other stores.

GraphStore for Knowledge Graph Traversals

Nodes and edges are represented by GraphNode and GraphEdge structs inside GraphStore (crates/velesdb-wasm/src/graph.rs). The store exposes BFS and DFS traversals via bfs_traverse and dfs_traverse, which accept a start node ID, depth limit, and result cap. Because the same GraphStore implementation compiles to WASM, browser-side and server-side graph queries share identical behavior.

ColumnStore for Structured Analytics

Structured payload fields reside in ColumnStore (crates/velesdb-core/src/column_store/mod.rs). Columns are typed (Int, Float, String, Bool) and stored column-wise, enabling cache-friendly scans and O(1) primary-key lookups. The store supports predicate pushdown for filters like price > 100, returning row IDs that intersect with vector or graph results.

VelesQL: The Unified Query Language

VelesDB exposes the three stores through VelesQL, a single SQL-like dialect parsed in crates/velesdb-core/src/velesql.rs.

Parsing and AST Generation

The Parser walks the token stream once and populates a unified AST that can contain:

• A SELECT node for vector/column queries
• A MATCH node for graph patterns
• Both nodes simultaneously for hybrid queries

Helper methods such as is_match(), has_vector_search(), and columns() allow the server to quickly dispatch the correct execution path without re-parsing.

Hybrid Query Execution

The server handlers in crates/velesdb-server/src/handlers/query.rs and crates/velesdb-server/src/handlers/match_query.rs inspect the parsed query:

• SELECT only → Run ANN via NativeHnswIndex::search, then apply column filters via ColumnStore.
• MATCH only → Execute GraphStore::bfs_traverse or dfs_traverse.
• Hybrid → Run vector search to obtain candidate IDs, feed those IDs into the graph engine via GraphStore::get_outgoing_by_label, and finally project columns from ColumnStore.

The result is a JSON array where each element contains nodeId, vectorScore, optional graphScore, and columnData, defined in crates/velesdb-wasm/src/lib.rs.

Practical Code Examples

Simple Vector Search

let collection = db.get_collection("embeds")?;
let query_vec = generate_embedding(128);
let top = collection.search(&query_vec, 5)?;   // uses HNSW
println!("{:?}", top);

Underlying path: Collection::search → VectorStore::search → NativeHnswIndex::search (crates/velesdb-core/src/index/hnsw/native_index.rs).

Pure Graph Traversal (BFS)

let coll = db.get_collection("social")?;
let graph = coll.graph_store();                // GraphStore inside the collection
let results = graph.bfs_traverse(42, 3, 10)?;   // start node 42, depth ≤3, max 10 results
println!("{:?}", results);

Underlying path: GraphStore::bfs_traverse (crates/velesdb-wasm/src/graph.rs).

Column-Filter on Payload

let res = db.query("
    SELECT id, title, price
    FROM products
    WHERE price > 100 AND category = 'electronics'
    LIMIT 20
")?;

Parser: Parser::parse detects a SELECT clause → ColumnStore is consulted (ColumnStore::get_value_as_json).

Hybrid Query – Vector Similarity + Graph Neighbourhood

let res = db.query("
    SELECT p.id, p.title, g.graph_score
    FROM documents AS p
    MATCH (p)-[:REFERS_TO]->(c)
    WHERE vector NEAR $q
    ORDER BY similarity(p.vec, $q) DESC
    LIMIT 10
")?;

Execution flow:

1. Parser builds an AST with both SELECT and MATCH parts (velesql.rs).
2. Server runs the ANN search → obtains candidate IDs.
3. Those IDs are fed to GraphStore::get_outgoing_by_label to fetch neighbours.
4. Column values (title, price) are read from ColumnStore.
5. Final rows are assembled with both vectorScore and graphScore.

Using the WASM Bindings from JavaScript

import { GraphStore, GraphNode, GraphEdge } from "velesdb-wasm";

const store = new GraphStore();
store.add_node(new GraphNode(1, "Article"));
store.add_node(new GraphNode(2, "Author"));
store.add_edge(new GraphEdge(10, 1, 2, "WRITTEN_BY"));
const neighbors = await store.bfs_traverse(1, 2, 10);
console.log(neighbors);   // [{nodeId:2, depth:1}]

Underlying Rust code: same GraphStore implementation used on the server, compiled to WASM (crates/velesdb-wasm/src/graph.rs).

Summary

• Unified Collection Model: Every collection in VelesDB aggregates a VectorStore, GraphStore, and ColumnStore defined in crates/velesdb-core/src/collection/types.rs, allowing vectors, graph edges, and structured metadata to coexist.
• Native HNSW Integration: Sub-millisecond ANN search is provided by NativeHnswIndex in crates/velesdb-core/src/index/hnsw/native_index.rs, backed by a contiguous VectorStore.
• Graph Traversal Engine: GraphStore in crates/velesdb-wasm/src/graph.rs implements BFS and DFS traversals via bfs_traverse and dfs_traverse, usable in both server and WASM environments.
• Columnar Analytics: ColumnStore in crates/velesdb-core/src/column_store/mod.rs stores typed columns for cache-friendly scans and O(1) primary-key lookups.
• VelesQL Unification: The parser in crates/velesdb-core/src/velesql.rs generates a unified AST supporting SELECT, MATCH, or hybrid clauses, while handlers in crates/velesdb-server/src/handlers/query.rs and match_query.rs dispatch execution across the three stores.

Frequently Asked Questions

How does VelesDB handle hybrid queries that combine vector similarity and graph traversal?

VelesDB processes hybrid queries by first parsing the VelesQL statement into a unified AST that contains both SELECT and MATCH nodes. The execution engine in crates/velesdb-server/src/handlers/match_query.rs runs the ANN search via NativeHnswIndex::search to obtain candidate IDs, then feeds those IDs into GraphStore::get_outgoing_by_label for traversal. Finally, it projects columns from ColumnStore and returns a result set containing both vectorScore and graphScore.

Can I use VelesDB's graph features in a browser environment?

Yes. The GraphStore implementation in crates/velesdb-wasm/src/graph.rs is compiled to WebAssembly and exposed via WASM bindings. You can instantiate GraphStore, add GraphNode and GraphEdge objects, and call bfs_traverse or dfs_traverse directly from JavaScript, using the same underlying Rust code that powers the server-side engine.

What indexing strategy does VelesDB use for vector search?

VelesDB uses a native HNSW (Hierarchical Navigable Small World) index implemented in crates/velesdb-core/src/index/hnsw/native_index.rs as NativeHnswIndex. Vectors are stored contiguously in VectorStore (crates/velesdb-core/src/index/hnsw/vector_store.rs) to maximize cache locality. The HNSW index provides sub-millisecond approximate nearest neighbor (ANN) queries, and the engine can intersect these results with graph traversals or column filters in hybrid queries.

How does VelesDB ensure fast filtering on structured payload data?

Structured payload fields are stored in ColumnStore (crates/velesdb-core/src/column_store/mod.rs), which organizes data column-wise with strict typing (Int, Float, String, Bool). This layout enables cache-friendly scans and O(1) primary-key lookups. When a VelesQL query contains a WHERE clause on payload fields, the execution engine applies predicate pushdown to ColumnStore, filtering rows before they are joined with vector or graph results.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}