feat(query): native hybrid multi-query (multiQuery()) (#217)

[s2x]

Closes #217.

Summary

queryMulti() runs each sub-query separately through the legacy scalar path and fuses in PHP. That cannot do hybrid search at all — the scalar path knows nothing about an FTS clause, so an FTS sub-query (which has no vector) aborted on Cannot instantiate FFI\CData of zero size. It also dropped everything living only in the C++ query handle, and keyed results by field name.

multiQuery() builds one upstream MultiQuery instead, so zvec runs the sub-queries in parallel and fuses in C++:

$docs = $collection->multiQuery(
    [$fts, new ZVecVectorQuery('embedding', $queryVector)],
    new ZVecRrfReRanker(),
    topk: 10,
    numCandidates: 100,
);

What the old path actually got wrong

1. FTS sub-queries crashed. The query has no vector, so building a float buffer from it failed at the FFI layer with an error that says nothing useful.
2. Per-query settings were silently lost. Everything that lives only in the C++ VectorQueryHolder never reached zvec_collection_query_ex: the FTS clause, DiskANN listSize, HNSW prefetch, setIncludeDocId(), setOutputFields().
3. Two sub-queries on one field dropped one of them — results were stored as $queryResults[$vq->fieldName] = $docs.

queryMulti() is unchanged for everything it supported, and now rejects the two cases it could not, naming multiQuery() as the alternative:

fts sub-query: queryMulti() cannot run FTS sub-queries; use multiQuery() for hybrid FTS + vector search
duplicate field: queryMulti() got two sub-queries on field 'vec'; use multiQuery() instead

The scores are deliberately not comparable

Upstream normalises weighted fusion per field with atan, not min-max, so the numbers differ from ZVecWeightedReRanker for identical inputs. RRF is the same 1/(k + rank + 1) in both. This is exactly why queryMulti() keeps its PHP fusion — changing it would have broken anyone relying on the values.

The test asserts the RRF arithmetic rather than just the ordering, which is what pinned down the actual rank assignment (d1 and d2 are rank 0 in different per-field lists, so both score 1/61 + 1/62):

scores are RRF: yes

Weighted fusion is positional

Upstream indexes weights by sub-query position, and duplicate field names are legal — so a field-keyed map has no unambiguous meaning. It is rejected explicitly rather than silently mapped in the wrong order:

field-keyed weights: multiQuery() needs positional weights (a list) because fusion is positional, not a field-keyed map

The FFI prefix is deliberate

zvec_ffi_multi_query_create, not zvec_multi_query_create. Upstream's own C API library exports those bare names with different signatures, and identical names with different ABIs is a trap. This follows the existing zvec_ffi_initialize convention.

One non-obvious detail

A sub-query that only set radius / linear / refiner has no query_params_ yet, so the adapter builds the right ones for the field's index type at execute time — otherwise upstream rejects the whole multi-query with a params-type mismatch. That is why MultiQueryHolder keeps full copies of the sub-queries rather than just their QueryTarget: those three values live on the holder.

Verification

Number of tests : 211               211
Tests skipped   :   0 (  0.0%)
Tests failed    :   0 (  0.0%)
Tests passed    : 209 ( 99.1%)

test_multivector_query, test_multivector_weighted, test_rerankers, test_reranker_in_query and test_fts all pass unchanged — the BC guarantee is tested, not just asserted.

Returns plain ZVecDoc[] rather than ZVecRerankedDoc[]: the fusion happened upstream, so there are no per-field source ranks to report.

Out of scope per the issue: sparse sub-queries (needs the sparse query-vector setter, #210), fromId() sub-queries, CallbackParams (a PHP callback invoked from C++), and group-by multi-query (upstream has none).

🤖 Generated with Claude Code