lora-python 0.11.5__tar.gz → 0.12.0__tar.gz

{lora_python-0.11.5 → lora_python-0.12.0}/Cargo.lock

@@ -773,7 +773,7 @@ checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
 
 [[package]]
 name = "lora-analyzer"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "lora-ast",
  "lora-builtins-meta",
@@ -784,14 +784,14 @@ dependencies = [
 
 [[package]]
 name = "lora-ast"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "smallvec 2.0.0-alpha.12",
 ]
 
 [[package]]
 name = "lora-binding-buffer"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "lora-database",
  "lora-store",
@@ -799,11 +799,11 @@ dependencies = [
 
 [[package]]
 name = "lora-builtins-meta"
-version = "0.11.5"
+version = "0.12.0"
 
 [[package]]
 name = "lora-compiler"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "lora-analyzer",
  "lora-ast",
@@ -812,7 +812,7 @@ dependencies = [
 
 [[package]]
 name = "lora-database"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "chacha20poly1305",
@@ -836,7 +836,7 @@ dependencies = [
 
 [[package]]
 name = "lora-executor"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "blake3",
  "crc32fast",
@@ -859,7 +859,7 @@ dependencies = [
 
 [[package]]
 name = "lora-ffi"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "lora-binding-buffer",
@@ -871,7 +871,7 @@ dependencies = [
 
 [[package]]
 name = "lora-node"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "lora-binding-buffer",
@@ -886,7 +886,7 @@ dependencies = [
 
 [[package]]
 name = "lora-parser"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "lora-ast",
  "pest",
@@ -897,7 +897,7 @@ dependencies = [
 
 [[package]]
 name = "lora-python"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "lora-database",
@@ -909,7 +909,7 @@ dependencies = [
 
 [[package]]
 name = "lora-query-wasm"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "console_error_panic_hook",
  "js-sys",
@@ -923,7 +923,7 @@ dependencies = [
 
 [[package]]
 name = "lora-server"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "axum",
@@ -937,7 +937,7 @@ dependencies = [
 
 [[package]]
 name = "lora-snapshot"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "argon2",
  "blake3",
@@ -946,12 +946,13 @@ dependencies = [
  "getrandom",
  "lora-store",
  "serde",
+ "serde_json",
  "thiserror",
 ]
 
 [[package]]
 name = "lora-store"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "crc32fast",
  "js-sys",
@@ -962,7 +963,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wal"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "crc32fast",
  "lora-store",
@@ -972,7 +973,7 @@ dependencies = [
 
 [[package]]
 name = "lora-wasm"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "console_error_panic_hook",
@@ -988,7 +989,7 @@ dependencies = [
 
 [[package]]
 name = "lora_ruby"
-version = "0.11.5"
+version = "0.12.0"
 dependencies = [
  "anyhow",
  "lora-database",

{lora_python-0.11.5 → lora_python-0.12.0}/Cargo.toml

@@ -4,7 +4,7 @@ resolver = "2"
 
 [workspace.package]
 edition = "2021"
-version = "0.11.5"
+version = "0.12.0"
 license = "BUSL-1.1"
 authors = ["LoraDB, Inc."]
 repository = "https://github.com/lora-db/lora"
@@ -15,17 +15,17 @@ rust-version = "1.87"
 # Internal crates — versions are kept in lockstep with [workspace.package].version
 # by `scripts/sync-versions.mjs`. Both `path` and `version` are set so that
 # `cargo publish` works (crates.io cannot resolve path-only deps).
-lora-ast = { path = "crates/lora-ast", version = "=0.11.5" }
-lora-parser = { path = "crates/lora-parser", version = "=0.11.5" }
-lora-builtins-meta = { path = "crates/lora-builtins-meta", version = "=0.11.5" }
-lora-analyzer = { path = "crates/lora-analyzer", version = "=0.11.5" }
-lora-compiler = { path = "crates/lora-compiler", version = "=0.11.5" }
-lora-store = { path = "crates/lora-store", version = "=0.11.5" }
-lora-snapshot = { path = "crates/lora-snapshot", version = "=0.11.5", default-features = false }
-lora-wal = { path = "crates/lora-wal", version = "=0.11.5" }
-lora-executor = { path = "crates/lora-executor", version = "=0.11.5", default-features = false }
-lora-database = { path = "crates/lora-database", version = "=0.11.5" }
-lora-binding-buffer = { path = "crates/bindings/lora-binding-buffer", version = "=0.11.5" }
+lora-ast = { path = "crates/lora-ast", version = "=0.12.0" }
+lora-parser = { path = "crates/lora-parser", version = "=0.12.0" }
+lora-builtins-meta = { path = "crates/lora-builtins-meta", version = "=0.12.0" }
+lora-analyzer = { path = "crates/lora-analyzer", version = "=0.12.0" }
+lora-compiler = { path = "crates/lora-compiler", version = "=0.12.0" }
+lora-store = { path = "crates/lora-store", version = "=0.12.0" }
+lora-snapshot = { path = "crates/lora-snapshot", version = "=0.12.0", default-features = false }
+lora-wal = { path = "crates/lora-wal", version = "=0.12.0" }
+lora-executor = { path = "crates/lora-executor", version = "=0.12.0", default-features = false }
+lora-database = { path = "crates/lora-database", version = "=0.12.0" }
+lora-binding-buffer = { path = "crates/bindings/lora-binding-buffer", version = "=0.12.0" }
 
 # External crates.
 anyhow = "1"

{lora_python-0.11.5 → lora_python-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lora-python
-Version: 0.11.5
+Version: 0.12.0
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8

{lora_python-0.11.5 → lora_python-0.12.0}/crates/lora-database/benches/fixtures.rs

@@ -22,10 +22,12 @@
 //! | `build_temporal_graph(n)`     | `:Event` / `:FOLLOWS`                | Events with date/time properties |
 //! | `build_spatial_graph(n)`      | `:Location` / `:CONNECTS_TO`         | Locations with point coords      |
 //! | `build_recommendation_graph`  | `:User`, `:Product` / `:BOUGHT`, etc | Bipartite user-product graph     |
+//! | `build_vector_graph(n, d, …)` | `:V`                                 | Vector index k-NN benchmarks     |
 
 use std::collections::BTreeMap;
 
 use lora_database::{Database, ExecuteOptions, InMemoryGraph, LoraValue, ResultFormat};
+use lora_store::{LoraVector, RawCoordinate, VectorCoordinateType};
 
 // ---------------------------------------------------------------------------
 // Wrapper (mirrors TestDb from integration tests but without serde_json dep)
@@ -600,3 +602,76 @@ pub fn build_recommendation_graph(n_users: usize, n_products: usize) -> BenchDb
 
     db
 }
+
+// ---------------------------------------------------------------------------
+// Vector graph builder
+// ---------------------------------------------------------------------------
+
+/// Deterministic LCG → f32 in roughly [-1, 1). Stable across platforms,
+/// no external dep. Used to seed vector fixtures so bench numbers are
+/// comparable across runs.
+fn vector_rng(seed: u64) -> impl FnMut() -> f32 {
+    let mut state = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15).wrapping_add(1);
+    move || {
+        state = state
+            .wrapping_mul(6364136223846793005)
+            .wrapping_add(1442695040888963407);
+        let bits = (state >> 32) as u32 as i32;
+        bits as f32 / (i32::MAX as f32 + 1.0)
+    }
+}
+
+/// Build a graph of `n` `:V` nodes each carrying a `dim`-dimensional
+/// FLOAT32 vector under property `e`, with a pre-created VECTOR index
+/// `vidx`, similarity function `sim` (`"cosine"` or `"euclidean"`),
+/// and index provider `provider` (`"flat"` or `"hnsw"`).
+///
+/// Vectors are deterministic so the same fixture produces identical
+/// content across runs. Used by `bench_vector_knn` to compare flat
+/// vs HNSW throughput.
+pub fn build_vector_graph(n: usize, dim: usize, sim: &str, provider: &str) -> BenchDb {
+    let db = BenchDb::with_capacity_hint(n, 0);
+    db.run(&format!(
+        "CREATE VECTOR INDEX vidx FOR (v:V) ON (v.e) \
+         OPTIONS {{indexConfig: {{ \
+            `vector.dimensions`: {dim}, \
+            `vector.similarity_function`: '{sim}', \
+            `vector.indexProvider`: '{provider}' \
+         }}}}",
+    ));
+
+    let mut rng = vector_rng(0x5EED);
+    // Each vector is dim * 4 bytes stored; intermediate RawCoordinate is
+    // 16 bytes per coord. Keep peak per-batch RSS bounded.
+    let batch = 1_000usize;
+    let mut i = 0usize;
+    while i < n {
+        let end = (i + batch).min(n);
+        let count = end - i;
+        let vecs: Vec<LoraValue> = (0..count)
+            .map(|_| {
+                let coords: Vec<RawCoordinate> = (0..dim)
+                    .map(|_| RawCoordinate::Float(rng() as f64))
+                    .collect();
+                LoraValue::Vector(
+                    LoraVector::try_new(coords, dim as i64, VectorCoordinateType::Float32)
+                        .expect("vector construction"),
+                )
+            })
+            .collect();
+        let params = BTreeMap::from([("vecs".to_string(), LoraValue::List(vecs))]);
+        db.run_with_params("UNWIND $vecs AS e CREATE (:V {e: e})", params);
+        i = end;
+    }
+    db
+}
+
+/// A single deterministic query vector with the given seed and dim.
+pub fn build_vector_query(seed: u64, dim: usize) -> LoraVector {
+    let mut rng = vector_rng(seed);
+    let coords: Vec<RawCoordinate> = (0..dim)
+        .map(|_| RawCoordinate::Float(rng() as f64))
+        .collect();
+    LoraVector::try_new(coords, dim as i64, VectorCoordinateType::Float32)
+        .expect("vector construction")
+}

{lora_python-0.11.5 → lora_python-0.12.0}/crates/lora-database/benches/query_implementations.rs

@@ -595,6 +595,65 @@ fn bench_advanced_query_shapes(c: &mut Criterion) {
     group.finish();
 }
 
+/// k-NN throughput across providers and scales.
+///
+/// Flat: the Phase 1 baseline — every call scores every vector.
+/// HNSW: the Phase 2 approximate index. d=384 matches a typical
+/// sentence-transformer embedding. The 100k cases dominate total
+/// bench time; restrict with e.g.
+/// `cargo bench -- vector_knn/n_100000_cosine_hnsw` during iteration.
+fn bench_vector_knn(c: &mut Criterion) {
+    let mut group = c.benchmark_group("query/vector_knn");
+    group.throughput(Throughput::Elements(1));
+    // 100k flat is ~50ms per query; 100k HNSW is sub-millisecond.
+    // Give criterion enough headroom on both ends without an
+    // intolerable suite runtime.
+    group.measurement_time(Duration::from_secs(5));
+    group.sample_size(20);
+
+    let dim = 384usize;
+    let k = 10usize;
+    let query = build_vector_query(0xDEAD_BEEF, dim);
+
+    // Flat at every scale (baseline curve).
+    for &n in &[1_000usize, 10_000, 100_000] {
+        for &sim in &["cosine", "euclidean"] {
+            let db = build_vector_graph(n, dim, sim, "flat");
+            let name = format!("n_{n}_{sim}_flat_k{k}_d{dim}");
+            group.bench_function(&name, |b| {
+                b.iter(|| {
+                    let params =
+                        BTreeMap::from([("q".to_string(), LoraValue::Vector(query.clone()))]);
+                    run_params(
+                        &db,
+                        "CALL db.index.vector.queryNodes('vidx', 10, $q) YIELD node, score",
+                        params,
+                    );
+                });
+            });
+        }
+    }
+
+    // HNSW only at scales where the ANN structure pays for its
+    // construction cost. n=1k is dominated by procedure overhead and
+    // doesn't move on either backend; skip.
+    for &n in &[10_000usize, 100_000] {
+        let db = build_vector_graph(n, dim, "cosine", "hnsw");
+        let name = format!("n_{n}_cosine_hnsw_k{k}_d{dim}");
+        group.bench_function(&name, |b| {
+            b.iter(|| {
+                let params = BTreeMap::from([("q".to_string(), LoraValue::Vector(query.clone()))]);
+                run_params(
+                    &db,
+                    "CALL db.index.vector.queryNodes('vidx', 10, $q) YIELD node, score",
+                    params,
+                );
+            });
+        });
+    }
+    group.finish();
+}
+
 criterion_group! {
     name = benches;
     config = bench_config();
@@ -606,7 +665,8 @@ criterion_group! {
         bench_writes,
         bench_expressions_and_functions,
         bench_typed_values,
-        bench_advanced_query_shapes
+        bench_advanced_query_shapes,
+        bench_vector_knn
 }
 
 criterion_main!(benches);

{lora_python-0.11.5 → lora_python-0.12.0}/crates/lora-database/src/database/procedures.rs

@@ -3,24 +3,25 @@
 //! These calls bypass the analyzer (which doesn't yet model standalone
 //! CALL). The cheap textual prefix router in [`is_procedure_call_text`]
 //! catches them, the parser produces a [`StandaloneCall`], and this
-//! module evaluates the procedure directly against the catalog + raw
-//! storage. The result is a flat row stream that the optional YIELD
-//! clause then projects.
+//! module evaluates the procedure directly against the catalog + the
+//! per-index backend exposed through [`GraphStorage::vector_search`].
+//! The result is a flat row stream that the optional YIELD clause
+//! then projects.
 //!
-//! kNN is computed with a flat scan: enumerate all label-matching
-//! entities, fetch the indexed property as [`LoraVector`], score, and
-//! keep the top `k` by descending similarity. Correctness only — a
-//! dedicated ANN structure is a follow-up.
+//! Top-k is built by sorting the backend's `(id, score)` output
+//! descending by score (tiebreak ascending by id) and truncating. The
+//! flat backend returns every label-matching entity; future ANN
+//! backends can return at most `k` and still satisfy the same
+//! contract.
 
 use std::any::Any;
-use std::collections::BTreeMap;
+use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::{anyhow, Result};
 use lora_ast::{Expr, ProcedureInvocationKind, StandaloneCall, YieldItem};
 use lora_executor::{LoraValue, Row};
 use lora_store::{
-    cosine_similarity_bounded, euclidean_similarity, GraphStorage, GraphStorageMut,
-    IndexDefinition, LoraVector, PropertyValue, StoredIndexEntity, StoredIndexKind,
+    GraphStorage, GraphStorageMut, IndexDefinition, LoraVector, StoredIndexEntity, StoredIndexKind,
     VectorCoordinateType,
 };
 
@@ -71,23 +72,25 @@ where
         params: &BTreeMap<String, LoraValue>,
         entity: StoredIndexEntity,
     ) -> Result<Vec<Row>> {
-        let (index_name, k, query_vec) = parse_vector_args(args, params)?;
+        let (index_name, k, query_vec, restrict_to) = parse_vector_args(args, params)?;
         let snapshot = self.read_store();
         let def = snapshot
             .get_index(&index_name)
             .ok_or_else(|| anyhow!("no vector index named `{index_name}`"))?;
 
         validate_procedure_index(&def, StoredIndexKind::Vector, entity, "vector")?;
-        let label = def
-            .label
-            .as_deref()
-            .ok_or_else(|| anyhow!("vector index `{index_name}` has no label/type"))?;
-        let property = def
-            .properties
-            .first()
-            .ok_or_else(|| anyhow!("vector index `{index_name}` has no property column"))?;
+        // Catalog sanity: the schema validator guarantees both fields
+        // exist, so any miss here is a corrupted catalog row, not user
+        // input.
+        if def.label.is_none() {
+            return Err(anyhow!("vector index `{index_name}` has no label/type"));
+        }
+        if def.properties.is_empty() {
+            return Err(anyhow!(
+                "vector index `{index_name}` has no property column"
+            ));
+        }
 
-        let similarity = similarity_from_definition(&def)?;
         let expected_dim = expected_dimension(&def);
         if let Some(dim) = expected_dim {
             if query_vec.dimension != dim {
@@ -99,7 +102,7 @@ where
             }
         }
 
-        let scored = score_entities(&*snapshot, entity, label, property, &query_vec, similarity);
+        let scored = snapshot.vector_search(&index_name, &query_vec, k, restrict_to.as_ref());
         Ok(scored_rows(scored, Some(k), entity))
     }
 
@@ -157,35 +160,6 @@ enum ProcedureKind {
     Fulltext,
 }
 
-#[derive(Clone, Copy)]
-enum Similarity {
-    Cosine,
-    Euclidean,
-}
-
-fn similarity_from_definition(def: &IndexDefinition) -> Result<Similarity> {
-    let sim = def
-        .options
-        .get("vector.similarity_function")
-        .and_then(|v| match v {
-            lora_store::IndexConfigValue::String(s) => Some(s.as_str()),
-            _ => None,
-        })
-        .ok_or_else(|| {
-            anyhow!(
-                "vector index `{}` is missing `vector.similarity_function`",
-                def.name
-            )
-        })?;
-    if sim.eq_ignore_ascii_case("cosine") {
-        Ok(Similarity::Cosine)
-    } else if sim.eq_ignore_ascii_case("euclidean") {
-        Ok(Similarity::Euclidean)
-    } else {
-        Err(anyhow!("unknown similarity function `{sim}`"))
-    }
-}
-
 fn expected_dimension(def: &IndexDefinition) -> Option<usize> {
     def.options.get("vector.dimensions").and_then(|v| match v {
         lora_store::IndexConfigValue::Integer(n) if *n > 0 => Some(*n as usize),
@@ -218,56 +192,6 @@ fn validate_procedure_index(
     Ok(())
 }
 
-fn score_entities<S: GraphStorage + ?Sized>(
-    storage: &S,
-    entity: StoredIndexEntity,
-    label: &str,
-    property: &str,
-    query: &LoraVector,
-    similarity: Similarity,
-) -> Vec<(u64, f64)> {
-    let mut scored: Vec<(u64, f64)> = Vec::new();
-    match entity {
-        StoredIndexEntity::Node => {
-            for id in storage.node_ids_by_label(label) {
-                let Some(record) = storage.node(id) else {
-                    continue;
-                };
-                let Some(PropertyValue::Vector(v)) = record.property(property) else {
-                    continue;
-                };
-                if let Some(score) = score_pair(v, query, similarity) {
-                    scored.push((id, score));
-                }
-            }
-        }
-        StoredIndexEntity::Relationship => {
-            for id in storage.rel_ids_by_type(label) {
-                let Some(record) = storage.relationship(id) else {
-                    continue;
-                };
-                let Some(PropertyValue::Vector(v)) = record.property(property) else {
-                    continue;
-                };
-                if let Some(score) = score_pair(v, query, similarity) {
-                    scored.push((id, score));
-                }
-            }
-        }
-    }
-    scored
-}
-
-fn score_pair(a: &LoraVector, b: &LoraVector, similarity: Similarity) -> Option<f64> {
-    if a.dimension != b.dimension {
-        return None;
-    }
-    match similarity {
-        Similarity::Cosine => cosine_similarity_bounded(a, b),
-        Similarity::Euclidean => euclidean_similarity(a, b),
-    }
-}
-
 fn scored_rows(
     mut scored: Vec<(u64, f64)>,
     limit: Option<usize>,
@@ -325,10 +249,10 @@ fn parse_fulltext_args(
 fn parse_vector_args(
     args: &[Expr],
     params: &BTreeMap<String, LoraValue>,
-) -> Result<(String, usize, LoraVector)> {
-    if args.len() != 3 {
+) -> Result<(String, usize, LoraVector, Option<BTreeSet<u64>>)> {
+    if args.len() < 3 || args.len() > 4 {
         return Err(anyhow!(
-            "vector procedure expects 3 arguments (indexName, k, query); got {}",
+            "vector procedure expects 3 or 4 arguments (indexName, k, query, options?); got {}",
             args.len()
         ));
     }
@@ -338,7 +262,81 @@ fn parse_vector_args(
         return Err(anyhow!("k must be positive"));
     }
     let query = eval_vector_arg(&args[2], params)?;
-    Ok((name, k, query))
+    let restrict_to = if args.len() == 4 {
+        parse_vector_options(&args[3], params)?
+    } else {
+        None
+    };
+    Ok((name, k, query, restrict_to))
+}
+
+/// Parse the optional 4th-argument options map. Currently the only
+/// honored key is `restrictTo`, a list of entity ids that limits
+/// returned results. Unknown keys are rejected so users notice
+/// typos at call time rather than silently getting unfiltered
+/// behaviour.
+fn parse_vector_options(
+    expr: &Expr,
+    params: &BTreeMap<String, LoraValue>,
+) -> Result<Option<BTreeSet<u64>>> {
+    let entries = match expr {
+        Expr::Map(items, _) => items.clone(),
+        // A $param map binding lands as LoraValue::Map after
+        // resolution; we don't currently take that path because
+        // resolve_literal would need a Map arm. For now, require an
+        // inline map literal in the procedure call.
+        other => {
+            return Err(anyhow!(
+                "vector procedure options must be a MAP literal like {{restrictTo: [...]}}, got {other:?}"
+            ));
+        }
+    };
+    let mut restrict_to: Option<BTreeSet<u64>> = None;
+    for (key, value) in entries {
+        match key.as_str() {
+            "restrictTo" => {
+                let resolved = resolve_literal(&value, params)?;
+                restrict_to = Some(coerce_id_set(&resolved)?);
+            }
+            other => {
+                return Err(anyhow!(
+                    "unknown option `{other}` for db.index.vector.queryNodes (known: `restrictTo`)"
+                ));
+            }
+        }
+    }
+    Ok(restrict_to)
+}
+
+fn coerce_id_set(value: &LoraValue) -> Result<BTreeSet<u64>> {
+    let items = match value {
+        LoraValue::List(xs) => xs,
+        other => {
+            return Err(anyhow!(
+                "`restrictTo` must be a LIST of node ids, got {other:?}"
+            ));
+        }
+    };
+    let mut out = BTreeSet::new();
+    for item in items {
+        match item {
+            LoraValue::Int(n) if *n >= 0 => {
+                out.insert(*n as u64);
+            }
+            LoraValue::Node(id) => {
+                out.insert(*id);
+            }
+            LoraValue::Relationship(id) => {
+                out.insert(*id);
+            }
+            other => {
+                return Err(anyhow!(
+                    "`restrictTo` entries must be non-negative integers or node/relationship references, got {other:?}"
+                ));
+            }
+        }
+    }
+    Ok(out)
 }
 
 fn eval_string_arg(