feat(ruvector-graph): VectorPropertyIndex — RaBitQ-backed kNN over node properties (Phase 1 item #2)

crates/ruvector-graph/Cargo.toml

@@ -15,6 +15,8 @@ ruvector-core = { version = "2.0.1", path = "../ruvector-core", default-features
 ruvector-raft = { version = "2.0.1", path = "../ruvector-raft", optional = true }
 ruvector-cluster = { version = "2.0.1", path = "../ruvector-cluster", optional = true }
 ruvector-replication = { version = "2.0.1", path = "../ruvector-replication", optional = true }
+# Optional vector-keyed property lookup via 1-bit RaBitQ codes.
+ruvector-rabitq = { path = "../ruvector-rabitq", optional = true }
 
 # Storage and indexing (optional for WASM)
 redb = { workspace = true, optional = true }
@@ -107,7 +109,7 @@ pest_generator = "2.7"
 default = ["full"]
 
 # Full feature set (non-WASM)
-full = ["simd", "storage", "async-runtime", "compression", "hnsw_rs", "ruvector-core/hnsw"]
+full = ["simd", "storage", "async-runtime", "compression", "hnsw_rs", "ruvector-core/hnsw", "rabitq"]
 
 # SIMD optimizations
 simd = ["ruvector-core/simd", "simsimd"]
@@ -139,6 +141,11 @@ metrics = ["prometheus"]
 # Full-text search support
 fulltext = []
 
+# Vector-keyed property lookup via RaBitQ 1-bit codes (`VectorPropertyIndex`).
+# Default-on under `full`; opt out with `--no-default-features` to keep a
+# graph-without-rabitq build alive (mirrors PR #383).
+rabitq = ["dep:ruvector-rabitq"]
+
 # Geospatial indexing
 geospatial = []
 
@@ -157,6 +164,11 @@ path = "examples/test_cypher_parser.rs"
 name = "new_capabilities_bench"
 harness = false
 
+[[bench]]
+name = "vector_property_index"
+harness = false
+required-features = ["rabitq"]
+
 [lib]
 crate-type = ["rlib"]
 bench = false

crates/ruvector-graph/benches/vector_property_index.rs

@@ -0,0 +1,95 @@
+//! Acceptance-shaped bench for `VectorPropertyIndex`. The roadmap target
+//! is recall@10 ≥ 0.95 at 100k×768 against brute force, with index
+//! memory ≤ 1/16 of the f32 baseline. Default `n` here is small enough
+//! to run on CI; override with `VECTOR_PROPERTY_INDEX_N=100000` to hit
+//! the full acceptance scale.
+
+use criterion::{criterion_group, criterion_main, Criterion};
+use rand::{Rng, SeedableRng};
+use ruvector_graph::{
+    GraphDB, NodeBuilder, PropertyValue, VectorPropertyIndex, VectorPropertyIndexConfig,
+};
+
+const PROP: &str = "embedding";
+
+fn clustered(n: usize, dim: usize, n_clusters: usize, seed: u64) -> Vec<Vec<f32>> {
+    let mut rng = rand::rngs::StdRng::seed_from_u64(seed);
+    let centroids: Vec<Vec<f32>> = (0..n_clusters)
+        .map(|_| (0..dim).map(|_| rng.gen::<f32>() * 4.0 - 2.0).collect())
+        .collect();
+    (0..n)
+        .map(|_| {
+            let c = &centroids[rng.gen_range(0..n_clusters)];
+            c.iter()
+                .map(|&x| x + (rng.gen::<f32>() - 0.5) * 0.3)
+                .collect()
+        })
+        .collect()
+}
+
+fn build_graph(vectors: &[Vec<f32>]) -> GraphDB {
+    let g = GraphDB::new();
+    for (i, v) in vectors.iter().enumerate() {
+        let node = NodeBuilder::new()
+            .id(format!("n-{i:08}"))
+            .label("Doc")
+            .property(PROP, PropertyValue::FloatArray(v.clone()))
+            .build();
+        g.create_node(node).unwrap();
+    }
+    g
+}
+
+fn run_bench(c: &mut Criterion) {
+    let n: usize = std::env::var("VECTOR_PROPERTY_INDEX_N")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(2000);
+    let dim: usize = std::env::var("VECTOR_PROPERTY_INDEX_DIM")
+        .ok()
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(128);
+
+    let vectors = clustered(n, dim, 32, 0xACCE57);
+    let graph = build_graph(&vectors);
+
+    c.bench_function(
+        &format!("vector_property_index/build/n={n}/dim={dim}"),
+        |b| {
+            b.iter(|| {
+                let _idx =
+                    VectorPropertyIndex::build(&graph, PROP, VectorPropertyIndexConfig::default())
+                        .unwrap();
+            });
+        },
+    );
+
+    let idx =
+        VectorPropertyIndex::build(&graph, PROP, VectorPropertyIndexConfig::default()).unwrap();
+
+    let mut rng = rand::rngs::StdRng::seed_from_u64(0xBA5E1);
+    let queries: Vec<Vec<f32>> = (0..50)
+        .map(|_| (0..dim).map(|_| rng.gen::<f32>() * 2.0 - 1.0).collect())
+        .collect();
+
+    let mut q_idx = 0usize;
+    c.bench_function(
+        &format!("vector_property_index/knn/k=10/n={n}/dim={dim}"),
+        |b| {
+            b.iter(|| {
+                let q = &queries[q_idx % queries.len()];
+                q_idx = q_idx.wrapping_add(1);
+                let _ = idx.knn(q, 10).unwrap();
+            });
+        },
+    );
+
+    eprintln!(
+        "[vector_property_index bench] n={n} dim={dim} codes={} B originals={} B",
+        idx.codes_bytes(),
+        idx.original_bytes()
+    );
+}
+
+criterion_group!(benches, run_bench);
+criterion_main!(benches);

crates/ruvector-graph/src/error.rs

@@ -78,6 +78,18 @@ pub enum GraphError {
 
     #[error("IO error: {0}")]
     IoError(#[from] std::io::Error),
+
+    /// Wrapping error from `ruvector-rabitq` while building / querying a
+    /// `VectorPropertyIndex`. Only constructed when the `rabitq` feature is on.
+    #[error("RaBitQ index error: {0}")]
+    RabitqIndex(String),
+}
+
+#[cfg(feature = "rabitq")]
+impl From<ruvector_rabitq::RabitqError> for GraphError {
+    fn from(err: ruvector_rabitq::RabitqError) -> Self {
+        GraphError::RabitqIndex(err.to_string())
+    }
 }
 
 impl From<anyhow::Error> for GraphError {

crates/ruvector-graph/src/graph.rs

@@ -362,6 +362,15 @@ impl GraphDB {
     pub fn hyperedge_count(&self) -> usize {
         self.hyperedges.len()
     }
+
+    /// Snapshot every `NodeId` currently stored in memory.
+    ///
+    /// Order is unspecified (DashMap shard order). Used by additive
+    /// helpers like `VectorPropertyIndex::build` that need to enumerate
+    /// nodes without depending on the internal storage shape.
+    pub fn node_ids(&self) -> Vec<NodeId> {
+        self.nodes.iter().map(|e| e.key().clone()).collect()
+    }
 }
 
 impl Default for GraphDB {

crates/ruvector-graph/src/lib.rs

@@ -25,6 +25,10 @@ pub mod hybrid;
 #[cfg(feature = "distributed")]
 pub mod distributed;
 
+// Vector-keyed property lookup via RaBitQ codes.
+#[cfg(feature = "rabitq")]
+pub mod vector_property_index;
+
 // Core type re-exports
 pub use edge::{Edge, EdgeBuilder};
 pub use error::{GraphError, Result};
@@ -50,6 +54,10 @@ pub use distributed::{
     ShardCoordinator, ShardStrategy,
 };
 
+// Re-export vector-property-index types when the rabitq feature is on.
+#[cfg(feature = "rabitq")]
+pub use vector_property_index::{VectorPropertyIndex, VectorPropertyIndexConfig};
+
 #[cfg(test)]
 mod tests {
     #[test]