sqlrite 0.1.10__tar.gz → 0.1.11__tar.gz

{sqlrite-0.1.10 → sqlrite-0.1.11}/Cargo.lock

@@ -3736,7 +3736,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-desktop"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "serde",
  "serde_json",
@@ -3748,7 +3748,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-engine"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "clap",
  "env_logger",
@@ -3763,7 +3763,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-ffi"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "cbindgen",
  "sqlrite-engine",
@@ -3771,7 +3771,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-nodejs"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "napi",
  "napi-build",
@@ -3781,7 +3781,7 @@ dependencies = [
 
 [[package]]
 name = "sqlrite-python"
-version = "0.1.10"
+version = "0.1.11"
 dependencies = [
  "pyo3",
  "sqlrite-engine",

{sqlrite-0.1.10 → sqlrite-0.1.11}/Cargo.toml

@@ -27,7 +27,7 @@ resolver = "3"
 # `package =` key so the import name stays `sqlrite` internally:
 #     sqlrite = { package = "sqlrite-engine", path = "…" }
 name = "sqlrite-engine"
-version = "0.1.10"
+version = "0.1.11"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.10 → sqlrite-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlrite
-Version: 0.1.10
+Version: 0.1.11
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{sqlrite-0.1.10 → sqlrite-0.1.11}/desktop/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sqlrite-desktop-frontend",
   "private": true,
-  "version": "0.1.10",
+  "version": "0.1.11",
   "type": "module",
   "scripts": {
     "dev": "vite",

{sqlrite-0.1.10 → sqlrite-0.1.11}/docs/phase-7-plan.md

@@ -106,12 +106,17 @@ SELECT id, title FROM docs ORDER BY embedding <-> [0.1, ...] LIMIT 10;
 - `<=>`  → `vec_distance_cosine`
 - `<#>`  → `vec_distance_dot`
 
+> **Scope correction (2026-04-27, during 7b implementation):** Operators turned out to be a much bigger parser change than Q6 anticipated. sqlparser-rs (current pinned version) **fails outright** on `<->` and `<#>` ("Expected: an expression, found: ->"). Only `<=>` parses, as MySQL's `Spaceship` (null-safe equality). Supporting all three operators requires either a fork of sqlparser to extend the SQLite dialect, or a string-preprocessing pass that rewrites operators to function calls before handing SQL to the parser — neither is the "tiny parser change" Q6 estimated.
+>
+> **Decision:** ship 7b with **functions only**. Operators are deferred to a follow-up sub-phase **7b.1**. The KNN use case (`ORDER BY vec_distance_l2(col, [...]) LIMIT k`) still works — just verbose. When 7b.1 lands, queries can switch from function-call form to operator form without any other behavior change.
+
 **Decisions:**
 
 - **Dispatch in the existing expression evaluator.** No new function-registration framework — these are built-in functions like `||` is.
-- **Operators land in the parser as new infix tokens.** sqlparser's SQLite dialect doesn't have these; we either extend the dialect or post-process the AST. Either is fine.
+- **Operators land in 7b.1, not 7b.** See scope-correction note above.
+- **`ORDER BY` widened to accept arbitrary expressions** as part of 7b. Pre-7b, the parser restricted ORDER BY to bare column refs; without expression support, KNN queries would have been impossible. New shape: `eval_expr` is called per-row to produce sort keys. This is a strict superset — `ORDER BY col` still works because `Expr::Identifier` takes the same path.
 
-**LOC estimate:** ~250 lines.
+**LOC estimate:** ~250 lines for the functions; another ~50 for the ORDER BY parser extension. Total ~300 LOC, slightly over Q-time estimate.
 
 **Tests:** all three distance metrics against hand-computed values; operator parsing; KNN result ordering.
 
@@ -296,10 +301,11 @@ let rows = conn.execute(&resp.sql)?;
 ## Implementation order + dependencies
 
 ```
-7a (VECTOR type)           — independent, foundational
-  └── 7b (distances)       — needs 7a
-        └── 7c (KNN exec)  — needs 7b
-              └── 7d (HNSW)— needs 7b/7c
+7a (VECTOR type)              — independent, foundational
+  └── 7b (distance functions) — needs 7a
+        └── 7b.1 (operators)  — sugar over 7b; deferred from 7b per scope correction
+        └── 7c (KNN exec opt) — needs 7b (operators not required)
+              └── 7d (HNSW)   — needs 7b/7c
 
 7e (JSON)                  — independent, can interleave anywhere
 

{sqlrite-0.1.10 → sqlrite-0.1.11}/docs/supported-sql.md

@@ -125,7 +125,7 @@ FROM <table>
 
 - **Projection**: `*` (all columns in declaration order) or a bare column list. Columns not declared on the table are rejected.
 - **`WHERE`**: any [expression](#expressions). Evaluated per row; NULL-as-false in WHERE context (three-valued logic collapsed to two-valued for filtering).
-- **`ORDER BY`**: single column, `ASC` (default) or `DESC`. Sort key types must match; mixing `INTEGER` and `TEXT` across rows under a single `ORDER BY` is a runtime error.
+- **`ORDER BY`**: single sort key, `ASC` (default) or `DESC`. The sort key can be a bare column reference OR any expression — including function calls — so KNN queries like `ORDER BY vec_distance_l2(embedding, [...]) LIMIT k` work end-to-end *(Phase 7b)*. Sort key types must match; mixing `INTEGER` and `TEXT` across rows under a single `ORDER BY` is a runtime error.
 - **`LIMIT`**: non-negative integer literal. `LIMIT 0` is valid (returns zero rows).
 
 ### Index probing
@@ -140,7 +140,7 @@ The executor includes a tiny optimizer: if the `WHERE` is exactly `<indexed_col>
 - **`DISTINCT`**
 - **`LIKE`**, **`IN`**, **`IS NULL`** / **`IS NOT NULL`**, `BETWEEN`
 - **Expressions in the projection list** (`SELECT age + 1 FROM users`) — projection is bare column references only
-- **Multi-column `ORDER BY`**, `NULLS FIRST/LAST`
+- **Multi-column `ORDER BY`**, `NULLS FIRST/LAST` (single sort key only; the sort key itself can be an expression as of Phase 7b)
 - **`OFFSET`**
 - **Column aliases** (`SELECT name AS n FROM users`)
 
@@ -196,6 +196,26 @@ Expressions work inside `WHERE` (both in `SELECT`, `UPDATE`, `DELETE`) and on th
 
 Same set accepted by `INSERT` (see [Value literals accepted](#value-literals-accepted)).
 
+### Built-in functions
+
+| Function | Returns | Notes |
+|---|---|---|
+| `vec_distance_l2(a, b)` | Real (f64) | Euclidean distance √Σ(aᵢ−bᵢ)². Smaller is closer. *(Phase 7b)* |
+| `vec_distance_cosine(a, b)` | Real (f64) | Cosine distance `1 − (a·b) / (‖a‖·‖b‖)`. Errors on zero-magnitude vectors (cosine is undefined). Smaller is closer; identical vectors return 0.0, orthogonal vectors return 1.0. *(Phase 7b)* |
+| `vec_distance_dot(a, b)` | Real (f64) | Negated dot product `−(a·b)`. Negation makes "smaller is closer" consistent with the others. For unit-norm vectors equals `vec_distance_cosine(a, b) - 1`. *(Phase 7b)* |
+
+All three vector-distance functions take exactly two arguments, both of which must be vectors of the same dimension. Either argument can be a column reference (`embedding`), a bracket-array literal (`[0.1, 0.2, 0.3]`), or any sub-expression that evaluates to a vector. Mismatched dimensions error with `vector dimensions don't match (lhs=N, rhs=M)`.
+
+The KNN ranking pattern that motivates this set:
+
+```sql
+SELECT id, title FROM docs
+ORDER BY vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0])
+LIMIT 10;
+```
+
+> **Operator forms (`<->` `<=>` `<#>`) are not supported yet.** They're the de facto pgvector convention but blocked on a sqlparser limitation — will land as a Phase 7b.1 follow-up. Use the function-call form for now.
+
 ### Type coercion in arithmetic
 
 - **Integer-only ops stay integer.** `1 + 2` → `3` (Integer).

{sqlrite-0.1.10 → sqlrite-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "sqlrite"
-version = "0.1.10"
+version = "0.1.11"
 description = "Python bindings for SQLRite — a small, embeddable SQLite clone written in Rust."
 authors = [{ name = "Joao Henrique Machado Silva", email = "joaoh82@gmail.com" }]
 license = { text = "MIT" }

{sqlrite-0.1.10 → sqlrite-0.1.11}/sdk/python/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "sqlrite-python"
-version = "0.1.10"
+version = "0.1.11"
 authors = ["Joao Henrique Machado Silva <joaoh82@gmail.com>"]
 edition = "2024"
 rust-version = "1.85"

{sqlrite-0.1.10 → sqlrite-0.1.11}/src/sql/executor.rs

@@ -5,14 +5,15 @@ use std::cmp::Ordering;
 
 use prettytable::{Cell as PrintCell, Row as PrintRow, Table as PrintTable};
 use sqlparser::ast::{
-    AssignmentTarget, BinaryOperator, CreateIndex, Delete, Expr, FromTable, Statement, TableFactor,
-    TableWithJoins, UnaryOperator, Update,
+    AssignmentTarget, BinaryOperator, CreateIndex, Delete, Expr, FromTable, FunctionArg,
+    FunctionArgExpr, FunctionArguments, ObjectNamePart, Statement, TableFactor, TableWithJoins,
+    UnaryOperator, Update,
 };
 
 use crate::error::{Result, SQLRiteError};
 use crate::sql::db::database::Database;
 use crate::sql::db::secondary_index::{IndexOrigin, SecondaryIndex};
-use crate::sql::db::table::{DataType, Table, Value};
+use crate::sql::db::table::{DataType, Table, Value, parse_vector_literal};
 use crate::sql::parser::select::{OrderByClause, Projection, SelectQuery};
 
 /// Executes a parsed `SelectQuery` against the database and returns a
@@ -500,18 +501,42 @@ fn try_extract_equality(expr: &Expr) -> Option<(String, sqlparser::ast::Value)>
 }
 
 fn sort_rowids(rowids: &mut [i64], table: &Table, order: &OrderByClause) -> Result<()> {
-    if !table.contains_column(order.column.clone()) {
-        return Err(SQLRiteError::Internal(format!(
-            "ORDER BY references unknown column '{}'",
-            order.column
-        )));
+    // Phase 7b: ORDER BY now accepts any expression (column ref,
+    // arithmetic, function call, …). Pre-compute the sort key for
+    // every rowid up front so the comparator is called O(N log N)
+    // times against pre-evaluated Values rather than re-evaluating
+    // the expression O(N log N) times. Not strictly necessary today,
+    // but vital once 7d's HNSW index lands and this same code path
+    // could be running tens of millions of distance computations.
+    let mut keys: Vec<(i64, Result<Value>)> = rowids
+        .iter()
+        .map(|r| (*r, eval_expr(&order.expr, table, *r)))
+        .collect();
+
+    // Surface the FIRST evaluation error if any. We could be lazy
+    // and let sort_by encounter it, but `Ord::cmp` can't return a
+    // Result and we'd have to swallow errors silently.
+    for (_, k) in &keys {
+        if let Err(e) = k {
+            return Err(SQLRiteError::General(format!(
+                "ORDER BY expression failed: {e}"
+            )));
+        }
     }
-    rowids.sort_by(|a, b| {
-        let va = table.get_value(&order.column, *a);
-        let vb = table.get_value(&order.column, *b);
-        let ord = compare_values(va.as_ref(), vb.as_ref());
+
+    keys.sort_by(|(_, ka), (_, kb)| {
+        // Both unwrap()s are safe — we just verified above that
+        // every key Result is Ok.
+        let va = ka.as_ref().unwrap();
+        let vb = kb.as_ref().unwrap();
+        let ord = compare_values(Some(va), Some(vb));
         if order.ascending { ord } else { ord.reverse() }
     });
+
+    // Write the sorted rowids back into the caller's slice.
+    for (i, (rowid, _)) in keys.into_iter().enumerate() {
+        rowids[i] = rowid;
+    }
     Ok(())
 }
 
@@ -558,7 +583,23 @@ fn eval_expr(expr: &Expr, table: &Table, rowid: i64) -> Result<Value> {
     match expr {
         Expr::Nested(inner) => eval_expr(inner, table, rowid),
 
-        Expr::Identifier(ident) => Ok(table.get_value(&ident.value, rowid).unwrap_or(Value::Null)),
+        Expr::Identifier(ident) => {
+            // Phase 7b — sqlparser parses bracket-array literals like
+            // `[0.1, 0.2, 0.3]` as bracket-quoted identifiers (it inherits
+            // MSSQL `[name]` syntax). When we see `quote_style == Some('[')`
+            // in expression-evaluation position (SELECT projection, WHERE,
+            // ORDER BY, function args), parse the bracketed content as a
+            // vector literal so the rest of the executor can compare /
+            // distance-compute against it. Same trick the INSERT parser
+            // uses; the executor needed its own copy because expression
+            // eval runs on a different code path.
+            if ident.quote_style == Some('[') {
+                let raw = format!("[{}]", ident.value);
+                let v = parse_vector_literal(&raw)?;
+                return Ok(Value::Vector(v));
+            }
+            Ok(table.get_value(&ident.value, rowid).unwrap_or(Value::Null))
+        }
 
         Expr::CompoundIdentifier(parts) => {
             // Accept `table.col` — we only have one table in scope, so ignore the qualifier.
@@ -659,12 +700,171 @@ fn eval_expr(expr: &Expr, table: &Table, rowid: i64) -> Result<Value> {
             ))),
         },
 
+        // Phase 7b — function-call dispatch. Currently only the three
+        // vector-distance functions; this match arm becomes the single
+        // place to register more SQL functions later (e.g. abs(),
+        // length(), …) without re-touching the rest of the executor.
+        //
+        // Operator forms (`<->` `<=>` `<#>`) are NOT plumbed here: two
+        // of three don't parse natively in sqlparser (we'd need a
+        // string-preprocessing pass or a sqlparser fork). Deferred to
+        // a follow-up sub-phase; see docs/phase-7-plan.md's "Scope
+        // corrections" note.
+        Expr::Function(func) => eval_function(func, table, rowid),
+
         other => Err(SQLRiteError::NotImplemented(format!(
             "unsupported expression in WHERE/projection: {other:?}"
         ))),
     }
 }
 
+/// Dispatches an `Expr::Function` to its built-in implementation.
+/// Currently only the three vec_distance_* functions; other functions
+/// surface as `NotImplemented` errors with the function name in the
+/// message so users see what they tried.
+fn eval_function(func: &sqlparser::ast::Function, table: &Table, rowid: i64) -> Result<Value> {
+    // Function name lives in `name.0[0]` for unqualified calls. Anything
+    // qualified (e.g. `pkg.fn(...)`) falls through to NotImplemented.
+    let name = match func.name.0.as_slice() {
+        [ObjectNamePart::Identifier(ident)] => ident.value.to_lowercase(),
+        _ => {
+            return Err(SQLRiteError::NotImplemented(format!(
+                "qualified function names not supported: {:?}",
+                func.name
+            )));
+        }
+    };
+
+    match name.as_str() {
+        "vec_distance_l2" | "vec_distance_cosine" | "vec_distance_dot" => {
+            let (a, b) = extract_two_vector_args(&name, &func.args, table, rowid)?;
+            let dist = match name.as_str() {
+                "vec_distance_l2" => vec_distance_l2(&a, &b),
+                "vec_distance_cosine" => vec_distance_cosine(&a, &b)?,
+                "vec_distance_dot" => vec_distance_dot(&a, &b),
+                _ => unreachable!(),
+            };
+            // Widen f32 → f64 for the runtime Value. Vectors are stored
+            // as f32 (consistent with industry convention for embeddings),
+            // but the executor's numeric type is f64 so distances slot
+            // into Value::Real cleanly and can be compared / ordered with
+            // other reals via the existing arithmetic + comparison paths.
+            Ok(Value::Real(dist as f64))
+        }
+        other => Err(SQLRiteError::NotImplemented(format!(
+            "unknown function: {other}(...)"
+        ))),
+    }
+}
+
+/// Extracts exactly two `Vec<f32>` arguments from a function call,
+/// validating arity and that both sides are Vector-typed with matching
+/// dimensions. Used by all three vec_distance_* functions.
+fn extract_two_vector_args(
+    fn_name: &str,
+    args: &FunctionArguments,
+    table: &Table,
+    rowid: i64,
+) -> Result<(Vec<f32>, Vec<f32>)> {
+    let arg_list = match args {
+        FunctionArguments::List(l) => &l.args,
+        _ => {
+            return Err(SQLRiteError::General(format!(
+                "{fn_name}() expects exactly two vector arguments"
+            )));
+        }
+    };
+    if arg_list.len() != 2 {
+        return Err(SQLRiteError::General(format!(
+            "{fn_name}() expects exactly 2 arguments, got {}",
+            arg_list.len()
+        )));
+    }
+    let mut out: Vec<Vec<f32>> = Vec::with_capacity(2);
+    for (i, arg) in arg_list.iter().enumerate() {
+        let expr = match arg {
+            FunctionArg::Unnamed(FunctionArgExpr::Expr(e)) => e,
+            other => {
+                return Err(SQLRiteError::NotImplemented(format!(
+                    "{fn_name}() argument {i} has unsupported shape: {other:?}"
+                )));
+            }
+        };
+        let val = eval_expr(expr, table, rowid)?;
+        match val {
+            Value::Vector(v) => out.push(v),
+            other => {
+                return Err(SQLRiteError::General(format!(
+                    "{fn_name}() argument {i} is not a vector: got {}",
+                    other.to_display_string()
+                )));
+            }
+        }
+    }
+    let b = out.pop().unwrap();
+    let a = out.pop().unwrap();
+    if a.len() != b.len() {
+        return Err(SQLRiteError::General(format!(
+            "{fn_name}(): vector dimensions don't match (lhs={}, rhs={})",
+            a.len(),
+            b.len()
+        )));
+    }
+    Ok((a, b))
+}
+
+/// Euclidean (L2) distance: √Σ(aᵢ − bᵢ)².
+/// Smaller-is-closer; identical vectors return 0.0.
+pub(crate) fn vec_distance_l2(a: &[f32], b: &[f32]) -> f32 {
+    debug_assert_eq!(a.len(), b.len());
+    let mut sum = 0.0f32;
+    for i in 0..a.len() {
+        let d = a[i] - b[i];
+        sum += d * d;
+    }
+    sum.sqrt()
+}
+
+/// Cosine distance: 1 − (a·b) / (‖a‖·‖b‖).
+/// Smaller-is-closer; identical (non-zero) vectors return 0.0,
+/// orthogonal vectors return 1.0, opposite-direction vectors return 2.0.
+///
+/// Errors if either vector has zero magnitude — cosine similarity is
+/// undefined for the zero vector and silently returning NaN would
+/// poison `ORDER BY` ranking. Callers who want the silent-NaN
+/// behavior can compute `vec_distance_dot(a, b) / (norm(a) * norm(b))`
+/// themselves.
+pub(crate) fn vec_distance_cosine(a: &[f32], b: &[f32]) -> Result<f32> {
+    debug_assert_eq!(a.len(), b.len());
+    let mut dot = 0.0f32;
+    let mut norm_a_sq = 0.0f32;
+    let mut norm_b_sq = 0.0f32;
+    for i in 0..a.len() {
+        dot += a[i] * b[i];
+        norm_a_sq += a[i] * a[i];
+        norm_b_sq += b[i] * b[i];
+    }
+    let denom = (norm_a_sq * norm_b_sq).sqrt();
+    if denom == 0.0 {
+        return Err(SQLRiteError::General(
+            "vec_distance_cosine() is undefined for zero-magnitude vectors".to_string(),
+        ));
+    }
+    Ok(1.0 - dot / denom)
+}
+
+/// Negated dot product: −(a·b).
+/// pgvector convention — negated so smaller-is-closer like L2 / cosine.
+/// For unit-norm vectors `vec_distance_dot(a, b) == vec_distance_cosine(a, b) - 1`.
+pub(crate) fn vec_distance_dot(a: &[f32], b: &[f32]) -> f32 {
+    debug_assert_eq!(a.len(), b.len());
+    let mut dot = 0.0f32;
+    for i in 0..a.len() {
+        dot += a[i] * b[i];
+    }
+    -dot
+}
+
 /// Evaluates an integer/real arithmetic op. NULL on either side propagates.
 /// Mixed Integer/Real promotes to Real. Divide/Modulo by zero → error.
 fn eval_arith(op: &BinaryOperator, l: &Value, r: &Value) -> Result<Value> {
@@ -766,3 +966,101 @@ fn convert_literal(v: &sqlparser::ast::Value) -> Result<Value> {
         ))),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // -----------------------------------------------------------------
+    // Phase 7b — Vector distance function math
+    // -----------------------------------------------------------------
+
+    /// Float comparison helper — distance results need a small epsilon
+    /// because we accumulate sums across many f32 multiplies.
+    fn approx_eq(a: f32, b: f32, eps: f32) -> bool {
+        (a - b).abs() < eps
+    }
+
+    #[test]
+    fn vec_distance_l2_identical_is_zero() {
+        let v = vec![0.1, 0.2, 0.3];
+        assert_eq!(vec_distance_l2(&v, &v), 0.0);
+    }
+
+    #[test]
+    fn vec_distance_l2_unit_basis_is_sqrt2() {
+        // [1, 0] vs [0, 1]: distance = √((1-0)² + (0-1)²) = √2 ≈ 1.414
+        let a = vec![1.0, 0.0];
+        let b = vec![0.0, 1.0];
+        assert!(approx_eq(vec_distance_l2(&a, &b), 2.0_f32.sqrt(), 1e-6));
+    }
+
+    #[test]
+    fn vec_distance_l2_known_value() {
+        // [0, 0, 0] vs [3, 4, 0]: √(9 + 16 + 0) = 5 (the classic 3-4-5 triangle).
+        let a = vec![0.0, 0.0, 0.0];
+        let b = vec![3.0, 4.0, 0.0];
+        assert!(approx_eq(vec_distance_l2(&a, &b), 5.0, 1e-6));
+    }
+
+    #[test]
+    fn vec_distance_cosine_identical_is_zero() {
+        let v = vec![0.1, 0.2, 0.3];
+        let d = vec_distance_cosine(&v, &v).unwrap();
+        assert!(approx_eq(d, 0.0, 1e-6), "cos(v,v) = {d}, expected ≈ 0");
+    }
+
+    #[test]
+    fn vec_distance_cosine_orthogonal_is_one() {
+        // Two orthogonal unit vectors should have cosine distance = 1.0
+        // (cosine similarity = 0 → distance = 1 - 0 = 1).
+        let a = vec![1.0, 0.0];
+        let b = vec![0.0, 1.0];
+        assert!(approx_eq(vec_distance_cosine(&a, &b).unwrap(), 1.0, 1e-6));
+    }
+
+    #[test]
+    fn vec_distance_cosine_opposite_is_two() {
+        // a and -a have cosine similarity = -1 → distance = 1 - (-1) = 2.
+        let a = vec![1.0, 0.0, 0.0];
+        let b = vec![-1.0, 0.0, 0.0];
+        assert!(approx_eq(vec_distance_cosine(&a, &b).unwrap(), 2.0, 1e-6));
+    }
+
+    #[test]
+    fn vec_distance_cosine_zero_magnitude_errors() {
+        // Cosine is undefined for the zero vector — error rather than NaN.
+        let a = vec![0.0, 0.0];
+        let b = vec![1.0, 0.0];
+        let err = vec_distance_cosine(&a, &b).unwrap_err();
+        assert!(format!("{err}").contains("zero-magnitude"));
+    }
+
+    #[test]
+    fn vec_distance_dot_negates() {
+        // a·b = 1*4 + 2*5 + 3*6 = 32. Negated → -32.
+        let a = vec![1.0, 2.0, 3.0];
+        let b = vec![4.0, 5.0, 6.0];
+        assert!(approx_eq(vec_distance_dot(&a, &b), -32.0, 1e-6));
+    }
+
+    #[test]
+    fn vec_distance_dot_orthogonal_is_zero() {
+        // Orthogonal vectors have dot product 0 → negated is also 0.
+        let a = vec![1.0, 0.0];
+        let b = vec![0.0, 1.0];
+        assert_eq!(vec_distance_dot(&a, &b), 0.0);
+    }
+
+    #[test]
+    fn vec_distance_dot_unit_norm_matches_cosine_minus_one() {
+        // For unit-norm vectors: dot(a,b) = cos(a,b)
+        // → -dot(a,b) = -cos(a,b) = (1 - cos(a,b)) - 1 = vec_distance_cosine(a,b) - 1.
+        // Useful sanity check that the two functions agree on unit vectors.
+        let a = vec![0.6f32, 0.8]; // unit norm: √(0.36+0.64) = 1
+        let b = vec![0.8f32, 0.6]; // unit norm too
+        let dot = vec_distance_dot(&a, &b);
+        let cos = vec_distance_cosine(&a, &b).unwrap();
+        assert!(approx_eq(dot, cos - 1.0, 1e-5));
+    }
+}

{sqlrite-0.1.10 → sqlrite-0.1.11}/src/sql/mod.rs

@@ -1269,4 +1269,134 @@ mod tests {
         assert_eq!(vectors[1], vec![1.0f32, 2.0]);
         assert_eq!(vectors[2], vec![2.0f32, 3.0]);
     }
+
+    // -----------------------------------------------------------------
+    // Phase 7b — vector distance functions through process_command
+    // -----------------------------------------------------------------
+
+    /// Builds a 3-row docs table with 2-dim vectors aligned along the
+    /// axes so the expected distances are easy to reason about:
+    ///   id=1: [1, 0]
+    ///   id=2: [0, 1]
+    ///   id=3: [1, 1]
+    fn seed_vector_docs() -> Database {
+        let mut db = Database::new("tempdb".to_string());
+        process_command(
+            "CREATE TABLE docs (id INTEGER PRIMARY KEY, e VECTOR(2));",
+            &mut db,
+        )
+        .expect("create");
+        process_command("INSERT INTO docs (e) VALUES ([1.0, 0.0]);", &mut db).expect("insert 1");
+        process_command("INSERT INTO docs (e) VALUES ([0.0, 1.0]);", &mut db).expect("insert 2");
+        process_command("INSERT INTO docs (e) VALUES ([1.0, 1.0]);", &mut db).expect("insert 3");
+        db
+    }
+
+    #[test]
+    fn vec_distance_l2_in_where_filters_correctly() {
+        // Distance from [1,0]:
+        //   id=1 [1,0]: 0
+        //   id=2 [0,1]: √2 ≈ 1.414
+        //   id=3 [1,1]: 1
+        // WHERE distance < 1.1 should match id=1 and id=3 (2 rows).
+        let mut db = seed_vector_docs();
+        let resp = process_command(
+            "SELECT * FROM docs WHERE vec_distance_l2(e, [1.0, 0.0]) < 1.1;",
+            &mut db,
+        )
+        .expect("select");
+        assert!(
+            resp.contains("2 rows returned"),
+            "expected 2 rows, got: {resp}"
+        );
+    }
+
+    #[test]
+    fn vec_distance_cosine_in_where() {
+        // [1,0] vs [1,0]: cosine distance = 0
+        // [1,0] vs [0,1]: cosine distance = 1 (orthogonal)
+        // [1,0] vs [1,1]: cosine distance = 1 - 1/√2 ≈ 0.293
+        // WHERE distance < 0.5 → id=1 and id=3 (2 rows).
+        let mut db = seed_vector_docs();
+        let resp = process_command(
+            "SELECT * FROM docs WHERE vec_distance_cosine(e, [1.0, 0.0]) < 0.5;",
+            &mut db,
+        )
+        .expect("select");
+        assert!(
+            resp.contains("2 rows returned"),
+            "expected 2 rows, got: {resp}"
+        );
+    }
+
+    #[test]
+    fn vec_distance_dot_negated() {
+        // [1,0]·[1,0] = 1 → -1
+        // [1,0]·[0,1] = 0 → 0
+        // [1,0]·[1,1] = 1 → -1
+        // WHERE -dot < 0 (i.e. dot > 0) → id=1 and id=3 (2 rows).
+        let mut db = seed_vector_docs();
+        let resp = process_command(
+            "SELECT * FROM docs WHERE vec_distance_dot(e, [1.0, 0.0]) < 0.0;",
+            &mut db,
+        )
+        .expect("select");
+        assert!(
+            resp.contains("2 rows returned"),
+            "expected 2 rows, got: {resp}"
+        );
+    }
+
+    #[test]
+    fn knn_via_order_by_distance_limit() {
+        // Classic KNN shape: ORDER BY distance LIMIT k.
+        // Distances from [1,0]: id=1=0, id=3=1, id=2=√2.
+        // LIMIT 2 should return id=1 then id=3 in that order.
+        let mut db = seed_vector_docs();
+        let resp = process_command(
+            "SELECT id FROM docs ORDER BY vec_distance_l2(e, [1.0, 0.0]) ASC LIMIT 2;",
+            &mut db,
+        )
+        .expect("select");
+        assert!(
+            resp.contains("2 rows returned"),
+            "expected 2 rows, got: {resp}"
+        );
+    }
+
+    #[test]
+    fn distance_function_dim_mismatch_errors() {
+        // 2-dim column queried with a 3-dim probe → clean error.
+        let mut db = seed_vector_docs();
+        let err = process_command(
+            "SELECT * FROM docs WHERE vec_distance_l2(e, [1.0, 0.0, 0.0]) < 1.0;",
+            &mut db,
+        )
+        .unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.to_lowercase().contains("dimension")
+                && msg.contains("lhs=2")
+                && msg.contains("rhs=3"),
+            "expected dim mismatch error, got: {msg}"
+        );
+    }
+
+    #[test]
+    fn unknown_function_errors_with_name() {
+        // Use the function in WHERE, not projection — the projection
+        // parser still requires bare column references; function calls
+        // there are a future enhancement (with `AS alias` support).
+        let mut db = seed_vector_docs();
+        let err = process_command(
+            "SELECT * FROM docs WHERE vec_does_not_exist(e, [1.0, 0.0]) < 1.0;",
+            &mut db,
+        )
+        .unwrap_err();
+        let msg = format!("{err}");
+        assert!(
+            msg.contains("vec_does_not_exist"),
+            "expected error mentioning function name, got: {msg}"
+        );
+    }
 }

{sqlrite-0.1.10 → sqlrite-0.1.11}/src/sql/parser/select.rs

@@ -14,10 +14,16 @@ pub enum Projection {
     Columns(Vec<String>),
 }
 
-/// An ORDER BY clause restricted to a single column, ascending by default.
+/// A parsed `ORDER BY` clause: a single sort key (expression), ascending
+/// by default. Phase 7b widened this from "bare column name" to
+/// "arbitrary expression" so KNN queries of the form
+/// `ORDER BY vec_distance_l2(col, [...]) LIMIT k` work end-to-end. The
+/// expression is evaluated per-row at execution time via `eval_expr`;
+/// the simple `ORDER BY col` form still works because that's just an
+/// `Expr::Identifier` taking the same path.
 #[derive(Debug, Clone)]
 pub struct OrderByClause {
-    pub column: String,
+    pub expr: Expr,
     pub ascending: bool,
 }
 
@@ -174,20 +180,15 @@ fn parse_order_by(order_by: Option<&sqlparser::ast::OrderBy>) -> Result<Option<O
         ));
     }
     let obe = &exprs[0];
-    let column = match &obe.expr {
-        Expr::Identifier(ident) => ident.value.clone(),
-        Expr::CompoundIdentifier(parts) => {
-            parts.last().map(|i| i.value.clone()).unwrap_or_default()
-        }
-        _ => {
-            return Err(SQLRiteError::NotImplemented(
-                "ORDER BY only supports a bare column name for now".to_string(),
-            ));
-        }
-    };
+    // Phase 7b: accept arbitrary expressions, not just bare column refs.
+    // The executor's `sort_rowids` evaluates this expression per row via
+    // `eval_expr`, which handles Identifier (column lookup), Function
+    // (vec_distance_*), arithmetic, etc. uniformly. The previous
+    // column-name-only restriction has been lifted.
+    let expr = obe.expr.clone();
     // `asc == None` is the dialect default (ASC).
     let ascending = obe.options.asc.unwrap_or(true);
-    Ok(Some(OrderByClause { column, ascending }))
+    Ok(Some(OrderByClause { expr, ascending }))
 }
 
 fn parse_limit(limit: Option<&LimitClause>) -> Result<Option<usize>> {