HeliosDB Nano v3.17.0 Release Notes

Release Date: 2026-04-24 Theme: Graph-RAG phase 3 MVP — universal cross-modal graph (opt-in)

Highlights

First landing for the universal cross-modal graph. _hdb_graph_nodes and _hdb_graph_edges are plain user tables (queryable, joinable, branch-aware). The phase 3 MVP ships embedded Rust API; SQL-level WITH CONTEXT clause, graph-weighted HNSW tie-breaking, and semantic-Merkle invalidation are follow-ups.

cargo build --release --features graph-rag
# graph-rag implies code-graph

What’s New

Universal Graph Schema

On first call, two tables bootstrap automatically:

-- Inspect the schema
\d _hdb_graph_nodes
\d _hdb_graph_edges

Schema (simplified):

_hdb_graph_nodes(node_id, kind, title, text, source_ref, props)
_hdb_graph_edges(edge_id, src_id, dst_id, kind, weight, props)

Both are plain user tables — you can read, write, index, and join them like any other table.

`graph_rag_project_symbols()`

let db = EmbeddedDatabase::new("./code.helio")?;
db.code_index(opts)?;                  // populate _hdb_code_*
db.graph_rag_project_symbols()?;       // project into _hdb_graph_*

Project every row of _hdb_code_symbols into _hdb_graph_nodes and every resolved row of _hdb_code_symbol_refs into _hdb_graph_edges. Idempotent. Tolerates the code-graph tables being absent (no-op when nothing to project).

`graph_rag_search(opts)`

use heliosdb_nano::graph_rag::SearchOpts;

let opts = SearchOpts {
    seed_text: "login".to_string(),
    seed_kinds: vec!["function".to_string()],
    edge_kinds: vec!["CALLS".to_string(), "REFERENCES".to_string()],
    max_hops: 3,
    limit: 50,
};
let result = db.graph_rag_search(opts)?;
// result.nodes, result.edges, result.hop_distances

Seed → BFS expand → return subgraph with hop distances. seed_text matches title/text case-insensitively. seed_kinds and edge_kinds push down through FilteredScan so bloom / zone-map / SIMD selection applies automatically.

Regression Coverage

tests/graph_rag_phase3.rs — 3 integration tests:

project_and_search_finds_symbol
empty_seed_text_errors
bfs_respects_hops

Out of Scope (Tracked for Phase 3.1+)

Hybrid-search + vector rerank on seeds → partial in v3.19 (centrality weighting)
Graph-weighted HNSW tie-breaking → v3.19 (post-rerank scoring)
Semantic-Merkle index → v3.19 (CREATE SEMANTIC HASH INDEX)
WITH CONTEXT SQL clause → future
Corpus ingestion adapters (ingest_docs, etc.) → v3.19 (Docling)
Entity linker for cross-modal MENTIONS edges → v3.19 (graph_rag_link_vector)

Migration

Additive. Tables only created on first call. Default builds (without graph-rag) compile and run unchanged.

Compatibility Matrix

Component	Version
PostgreSQL wire	14, 15, 16
MySQL wire	5.7, 8.0
MCP protocol	1.0
tree-sitter	0.23