feat: rename vector_usearch to vector_search_vector, return full rows (#22)

* fix(rule): preserve hidden distance for sort

Keep _distance in an inner projection when ORDER BY uses a vector\ndistance expression that is not part of the final select list.\n\nThis fixes split-provider execution for queries like SELECT id ORDER\nBY l2_distance(vector, ARRAY[...]) LIMIT k while preserving the final\noutput schema. Add an execution test for the direct ORDER BY shape to\ncover the production case.

* style(rule): format hidden distance rewrite

* test(rule): cover computed sort projections

* refactor: make usearch_search, attach_distances, provider_key_col_idx pub(crate)

These helpers are needed by the new vector_search_vector UDTF to reuse
the same HNSW search → fetch → attach pattern as the ORDER BY path.

* feat: rename vector_usearch to vector_search_vector, return full rows

Replace the old vector_usearch UDTF that returned only (key, _distance)
with vector_search_vector that returns all table columns plus _distance.

New signature:
  vector_search_vector('conn.schema.table', 'column', ARRAY[...], k)

The UDTF reuses usearch_search, attach_distances, and provider_key_col_idx
from the planner module to follow the same HNSW search → fetch_by_keys →
attach_distances pattern as the ORDER BY execution path.

* docs: update README for vector_search_vector UDTF

Update UDTF section to reflect the new vector_search_vector signature
and full-row return schema. Update module structure reference.

* fix: use f64 precision for UDTF query vectors, add UDTF tests

Parse query vectors as f64 to match the optimizer path's precision,
avoiding silent accuracy loss for F64-quantized indexes.

Add 5 tests for vector_search_vector: basic happy path, projection
pushdown, bad table ref error, registry miss error, k > dataset size.

Author: anoop-narang

README.md

@@ -144,17 +144,31 @@ See [Adaptive filtering](#adaptive-filtering) for details on how the execution p
 
 ### UDTF path
 
-For runtime query vectors, complex joins, or explicit over-fetch control:
+`vector_search_vector` provides an explicit table function for ANN search, returning all table columns plus `_distance`:
 
 ```sql
-SELECT vs.key, vs._distance, d.title
-FROM vector_usearch('my_table', ARRAY[0.1, 0.2, ...], 20) vs
-JOIN my_table d ON d.id = vs.key
-ORDER BY vs._distance ASC
-LIMIT 10
+SELECT id, title, _distance
+FROM vector_search_vector('conn.schema.table', 'column', ARRAY[0.1, 0.2, ...], 10)
+ORDER BY _distance ASC
 ```
 
-The UDTF always calls `index.search()` directly — no filter absorption. Apply `WHERE` on the outer query to post-filter.
+| Argument | Type | Description |
+|---|---|---|
+| table | string literal | Dot-separated table reference: `'conn.schema.table'` |
+| column | string literal | Vector column with a registered index |
+| query | `ARRAY[...]` literal | Query vector |
+| k | integer | Number of nearest neighbors to return |
+
+The UDTF calls `resolve()` (sync, cache-only) on the registry — the index must already be loaded before the query is planned. It always calls `index.search()` directly — no filter absorption. Apply `WHERE` on the outer query to post-filter.
+
+```sql
+-- With filtering, aggregation, etc.
+SELECT category, COUNT(*) AS cnt, AVG(_distance) AS avg_dist
+FROM vector_search_vector('conn.schema.table', 'embedding', ARRAY[...], 50)
+WHERE category = 'nlp'
+GROUP BY category
+ORDER BY avg_dist
+```
 
 ### Tuning
 
@@ -205,7 +219,7 @@ src/
   rule.rs      — USearchRule: optimizer rewrite rule
   planner.rs   — USearchExecPlanner, USearchExec: physical execution
   udf.rs       — l2_distance, cosine_distance, negative_dot_product scalar UDFs
-  udtf.rs      — vector_usearch table function
+  udtf.rs      — vector_search_vector table function
   lookup.rs    — PointLookupProvider trait + HashKeyProvider
   keys.rs      — DatasetLayout, pack_key/unpack_key key encoding
 
@@ -292,6 +306,6 @@ Tests cover optimizer rule matching/rejection, end-to-end execution through both
 | Limitation | Notes |
 |---|---|
 | Stacked `Filter` nodes | Only one `Filter -> TableScan` layer is absorbed. `Filter -> Filter -> TableScan` falls back to exact execution. DataFusion typically combines multiple WHERE conditions into a single Filter, so this rarely occurs. |
-| Runtime query vectors | The query vector must be a compile-time literal (`ARRAY[0.1, ...]`). Column references or subquery results are not rewritten. Use the UDTF path for runtime vectors. |
+| Runtime query vectors | The query vector must be a compile-time literal (`ARRAY[0.1, ...]`). Column references or subquery results are not rewritten. Use `vector_search_vector` for explicit ANN queries. |
 | `ef_search` per-query | `expansion_search` is global to the index instance. Per-query adjustment is not supported. |
 | No DELETE / compaction | USearch soft-deletes entries but requires a full rebuild to reclaim space. |

src/lib.rs

@@ -80,7 +80,7 @@ pub use registry::{
 };
 pub use rule::USearchRule;
 pub use udf::{cosine_distance_udf, l2_distance_udf, negative_dot_product_udf};
-pub use udtf::USearchUDTF;
+pub use udtf::VectorSearchVectorUDTF;
 
 #[cfg(feature = "parquet-provider")]
 pub use parquet_provider::ParquetLookupProvider;
@@ -99,7 +99,8 @@ use datafusion::prelude::SessionContext;
 /// - `l2_distance(col, query)`          — squared Euclidean distance (L2sq)
 /// - `cosine_distance(col, query)`      — cosine distance
 /// - `negative_dot_product(col, query)` — negated inner product
-/// - `vector_usearch(table, query, k)`  — explicit ANN table function
+/// - `vector_search_vector('conn.schema.table', 'column', ARRAY[...], k)`
+///   — explicit ANN table function returning full rows + `_distance`
 ///   (cache-only for async-backed resolvers; does not trigger async loads)
 /// - [`USearchRule`]                    — optimizer rewrite rule
 ///
@@ -110,10 +111,8 @@ pub fn register_all(ctx: &SessionContext, registry: Arc<dyn VectorIndexResolver>
     ctx.register_udf(ScalarUDF::new_from_impl(cosine_distance_udf()));
     ctx.register_udf(ScalarUDF::new_from_impl(negative_dot_product_udf()));
     ctx.register_udtf(
-        "vector_usearch",
-        // `vector_usearch()` is synchronous and therefore cache-only for
-        // async-backed resolvers.
-        Arc::new(USearchUDTF::new(registry.clone())),
+        "vector_search_vector",
+        Arc::new(VectorSearchVectorUDTF::new(registry.clone())),
     );
     ctx.add_optimizer_rule(Arc::new(USearchRule::new(registry)));
     Ok(())

src/planner.rs

@@ -616,7 +616,7 @@ async fn adaptive_filtered_execute(
 
 /// Call `index.search` with the native scalar type appropriate for the column.
 /// Converts the usearch error into a `DataFusionError::Execution`.
-fn usearch_search(
+pub(crate) fn usearch_search(
     index: &usearch::Index,
     query_f64: &[f64],
     k: usize,
@@ -797,7 +797,7 @@ fn compute_raw_distance_f64(v: &[f64], q: &[f64], dist_type: &DistanceType) -> f
 /// Extract the distance from a single row of a vector column.
 ///
 /// Index of the key column in the lookup provider schema.
-fn provider_key_col_idx(registered: &crate::registry::RegisteredTable) -> Result<usize> {
+pub(crate) fn provider_key_col_idx(registered: &crate::registry::RegisteredTable) -> Result<usize> {
     registered
         .lookup_provider
         .schema()
@@ -813,7 +813,7 @@ fn provider_key_col_idx(registered: &crate::registry::RegisteredTable) -> Result
 // ── Distance attachment ───────────────────────────────────────────────────────
 
 /// Append a `_distance: Float32` column to each batch.
-fn attach_distances(
+pub(crate) fn attach_distances(
     batches: Vec<RecordBatch>,
     key_col_idx: usize,
     key_to_dist: &HashMap<u64, f32>,

src/udf.rs

@@ -3,8 +3,7 @@
 // Each takes (vector_col: FixedSizeList<Float32>, query: Array/Scalar) and
 // returns a Float32 distance per row.
 //
-// These are identical to the vector_search UDFs but kept in this module so
-// vector_usearch is fully self-contained (no dependency on vector_search).
+// These are kept in this module alongside the UDTF and optimizer rule.
 
 use std::any::Any;
 use std::hash::{Hash, Hasher};