Phase 7b: vector distance functions + ORDER BY expressions (operators deferred to 7b.1)

[joaoh82]

Summary

Three vector-distance SQL functions wired into the executor's expression evaluator — plus the ORDER BY parser change that makes KNN queries actually work end-to-end.

-- Single distance computation in WHERE
SELECT id FROM docs
WHERE vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0]) < 0.5;

-- KNN: sort by distance, take top-k
SELECT id FROM docs
ORDER BY vec_distance_l2(embedding, [0.1, 0.2, ..., 0.0]) ASC
LIMIT 10;

What lands

	What	Where
Functions	vec_distance_l2 / vec_distance_cosine / vec_distance_dot	src/sql/executor.rs — new eval_function dispatch
Bracket literals in expressions	Expr::Identifier with quote_style == Some('[') parses as Value::Vector	src/sql/executor.rs
ORDER BY expressions	Parser + executor accept any expression (was bare column refs only)	src/sql/parser/select.rs + src/sql/executor.rs

All three distance functions return Value::Real(f64). Internal math is f32 (matches Vec from VECTOR(N) columns); widened at the return boundary so distances slot into the existing arithmetic/comparison paths.

Scope correction (recorded in docs/phase-7-plan.md)

Q6 anticipated pgvector-style operators (<-> / <=> / <#>) as a "tiny parser change." Reality: sqlparser fails outright on <-> and <#> ("Expected: an expression, found: ->"); only <=> parses (as MySQL Spaceship). Supporting all three needs either a sqlparser fork or a SQL-string preprocessor — neither tiny.

Decision: ship functions only. Operators move to Phase 7b.1 follow-up.

KNN queries still work — just verbose. 7b.1 will swap function-call form to operator form without any other behavior change.

Tests

• 200 lib tests passing (was 184 — +16 new)
• Unit tests on the math:
  • identical-is-zero, orthogonal-is-1 (cosine)
  • 3-4-5 triangle (l2)
  • unit-norm dot ≡ cosine - 1
  • zero-magnitude cosine errors clean
  • dot product negation
• End-to-end via process_command:
  • WHERE filter for each of the 3 functions
  • KNN-shape ORDER BY … LIMIT
  • Dim-mismatch clean error (lhs=2, rhs=3)
  • Unknown-function error mentions function name

What stays out of scope (intentionally)

• Operator forms (<->, <=>, <#>) — Phase 7b.1
• Function calls in projection (SELECT vec_distance_l2(...) AS dist FROM ...) — needs AS alias support; future polish
• Multi-column ORDER BY — still single sort key
• HNSW index probing — Phase 7d. Today this is full-scan + sort.

Verified clean

• cargo fmt --all -- --check — clean
• cargo check --workspace --exclude sqlrite-python --exclude sqlrite-nodejs — clean
• cargo check -p sqlrite-python -p sqlrite-nodejs — clean
• cd sdk/wasm && cargo check — clean
• cargo test -p sqlrite-engine --lib — 200/200
• No file format change (no v5; the v4 envelope already covers this work)

🤖 Generated with Claude Code