fix(local): skip missing multivectors during search

[mikemikimike]

Fixes #1383

Summary

• Treat empty multivector matrices as non-matching points during local distance calculation.
• Preserve normal scoring while allowing the existing deleted-vector mask to skip missing vectors.
• Add a local regression test for searching a named multivector when another point has no value for it.

Testing

• pytest -q qdrant_client/local/tests/test_distances.py qdrant_client/local/tests/test_vectors.py
• pytest -q qdrant_client/local/tests
• uv tool run --from ruff==0.4.3 ruff check qdrant_client/local/multi_distances.py qdrant_client/local/tests/test_vectors.py
• git diff --check

The full test suite reached 78 passed and 2 skipped before tests/congruence_tests/test_aliases.py failed because the local Qdrant endpoint at localhost:6333 returned HTTP 502.

[netlify]

✅ Deploy Preview for poetic-froyo-8baba7 ready!

Name	Link
🔨 Latest commit	02e95b0
🔍 Latest deploy log	https://app.netlify.com/projects/poetic-froyo-8baba7/deploys/6a91970b98d1fc00086d11f4
😎 Deploy Preview	https://deploy-preview-1385--poetic-froyo-8baba7.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 61975553-ccf8-4a2c-9433-3ced184c6ee8

📥 Commits

Reviewing files that changed from the base of the PR and between 459897f and 02e95b0.

📒 Files selected for processing (2)

• qdrant_client/local/multi_distances.py
• qdrant_client/local/tests/test_vectors.py

🚧 Files skipped from review as they are similar to previous changes (2)

• qdrant_client/local/multi_distances.py
• qdrant_client/local/tests/test_vectors.py

Included review availability: Your plan provides up to 4 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The local multivector distance calculation now detects empty matrices, records a similarity of -np.inf, and continues without calling the distance function. A regression test verifies that a multivector search skips points without the requested vector.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 02e95

This localized change handles missing multivectors during local search while preserving normal scoring, with targeted regression coverage; no actionable merge-blocking risk remains beyond normal checks and review.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the local multivector search fix and matches the primary change.
Description check	✅ Passed	The description explains the missing-multivector behavior, the implementation, regression coverage, and test results.
Linked Issues check	✅ Passed	The changes address issue #1383 by treating empty multivector matrices as non-matching points and adding a regression test for points without the queried multivector.
Out of Scope Changes check	✅ Passed	All changes support the linked issue: they modify local multivector distance handling and add focused tests. No unrelated code changes are identified.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Gronoxx]

Issue author here. The -inf approach looks right to me. It keeps the deleted-vector mask as the single place that decides skipping, instead of adding a second guard, and it covers my case: a collection mixing points with and without the named multivector.

Caveat: this is from reading the diff. I haven't run your branch against my reproduction yet.

[Gronoxx]

Ran my reproduction against this branch, plus a set of cases around it.

The reported case. On qdrant-client==1.18.0 it raises IndexError: invalid index to scalar variable.. On this branch there is no error, and the point without the multivector is skipped instead of matched.

Why your approach beats the one I suggested. In the issue I proposed reshaping the placeholder to np.empty((0, size)). I implemented that in all four places the 1-D placeholder is created and tested it. The IndexError does disappear at np.linalg.norm, but the failure moves to np.max(sim_matrix, axis=-1) in calculate_multi_distance_core, as ValueError: zero-size array to reduction operation maximum which has no identity. An empty set has no maximum. Skipping before the reduction avoids both, so my suggestion would not have been enough on its own.

It fixes more than what I reported. The guard sits in calculate_multi_distance_core, which has ten call sites, so the same IndexError is gone from recommend, discover, context search and MMR. All four raise on 1.18.0 and work here.

Regressions I looked for and did not find. Scores for non-empty multivectors are bit-identical to 1.18.0 across three points with 2, 1 and 3 tokens. All four distances behave. -inf never reaches the result, not at limit=1000 and not at score_threshold=-1e30, so JSON serialization stays valid. Same through query_batch_points, with a query_filter, and on a collection persisted to disk and reopened. With four valid points and one missing the vector, all four still come back. Local suite: 73 passed.

One adjacent case, outside this issue's scope. An explicitly empty multivector (vector={"multi": []}) still raises the same IndexError on the write path, in _add_point, _update_point and _update_named_vectors, from the same np.linalg.norm(vector_np, axis=-1)[:, np.newaxis] pattern. That is unchanged from 1.18.0 and not something I reported. I traced it only as far as my time allowed, so I am not certain whether an empty multivector is meant to be valid input in the first place. Flagging it in case it deserves a separate issue.