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

> Discover how VelesDB unifies vector search graph databases and column stores using its VelesQL engine for powerful hybrid queries in one SQL-like syntax.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: deep-dive
- Published: 2026-02-28

---

**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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/handlers/query.rs) and [`crates/velesdb-server/src/handlers/match_query.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-wasm/src/lib.rs).

## Practical Code Examples

### Simple Vector Search

```rust
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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-core/src/index/hnsw/native_index.rs)).

### Pure Graph Traversal (BFS)

```rust
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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-wasm/src/graph.rs)).

### Column-Filter on Payload

```rust
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

```rust
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`](https://github.com/cyberlife-coder/velesdb/blob/main/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

```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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/crates/velesdb-server/src/handlers/query.rs) and [`match_query.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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.