fix(udf): compare row against row when both arguments are columns

[anoop-narang]

The bug

A distance function given a column as its second argument silently compared every row against row 0 of that column.

SELECT id, cosine_distance(emb, emb) AS self_dist FROM t ORDER BY id

Each row's own vector against itself must be 0 for every row. Instead:

id  self_dist
1   0.0
2   0.86683166      <- must be 0
3   0.92379284
4   0.8087635

No error and no warning. And it is not stable: adding WHERE id >= 3 moves the 0 onto row 3, because the filter changes which row leads the scan. The same query over the same data can give different answers depending on batching, filtering, or parallelism.

extract_query_vec resolves argument 2 to a single vector, taking .value(0) when handed an array. That is correct for the intended shape — one query vector — but silently wrong for a column.

What it should do

Row-wise: row i of argument 1 against row i of argument 2. That is how every scalar function over two columns behaves, and it is what DuckDB does:

                          DuckDB       before        after
array_cosine_distance(emb, emb)   0, 0, 0      0, 1, 1       0, 0, 0
array_cosine_distance(emb, [1,0,0])  0, 1, 1   0, 1, 1       0, 1, 1

Only the column-against-column case diverged; the literal query-vector form was already correct and is unchanged.

The change

• Second argument is an array with the same row count as the first → compare row against row.
• Second argument is a scalar, a literal, or a single-row array → broadcast to every row, exactly as before. This is the documented form and it is untouched.
• Second argument is an array of any other length → an error naming both lengths, rather than silently using row 0.

Nulls on either side yield a null distance, matching the existing single-vector path. Per-row dimensionality mismatches error, as they already did.

Verification

Expected values are DuckDB's, taken from array_cosine_distance / array_distance over the same three orthogonal unit vectors.

Confirmed the tests fail without the fix and pass with it:

without fix   self_distance_is_zero_on_every_row       FAILED  [0.0, 1.0, 1.0]
              self_distance_is_unchanged_by_a_filter   FAILED  [0.0, 1.0]
              l2_pairwise_compares_row_against_row     FAILED  [0.0, 2.0, 2.0]
              a_literal_query_vector_still_broadcasts  ok      <- documented path unaffected
with fix      all four                                 ok

Full suite: 78 passed, 0 failed (3 pre-existing ignored). clippy and fmt clean.

Note on l2_distance

While writing the oracle comparison: this crate's l2_kernel returns L2 squared, deliberately, to match USearch's MetricKind::L2sq. So l2_distance gives 2.0 for an orthogonal unit pair where DuckDB's array_distance gives 1.414. Ranking is identical since squaring is monotonic, so k-NN results agree — but absolute values do not, which matters for a threshold ported from DuckDB. Not changed here; pinned in a test so the convention is asserted rather than assumed.

[claude]

All four prior threads are addressed in the code, not only in replies.

The type-based rule in is_vector_column (src/udf.rs:265) keeps the flat query-vector branches of extract_query_vec reachable, and the (1, _) arm handles a query vector on the left. try_extract_distance (src/rule.rs:492) rejects a column as the second argument, so the row-wise case cannot be rewritten into an ANN search.

Two non-blocking comments on README.md. CI Test and Clippy had not reported when this review started.

[claude]

Prior threads are all resolved in code. Verified try_extract_distance (src/rule.rs:488-492) matches the new Limitations row, and the flat-array branches in extract_query_vec are reachable again through the non-list arm at src/udf.rs:156. No new findings.