fix: validate local query parameters

[adityat210]

All Submissions:

• Contributions should target the dev branch. Did you create your branch from dev?
• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?

Problem

Local mode accepted several invalid query bounds that the server rejects:

• negative Query API offsets could silently truncate the result set
• zero nested-prefetch limits were treated as the default limit
• zero group sizes produced groups with no hits
• invalid matrix limits and samples returned empty responses

The server schemas define Query API offset >= 0 and limit >= 1, grouped-query group_size >= 1, and matrix limit >= 1 / sample >= 2. See the Query points, Query point groups, and Distance matrix offsets references.

This follows the local/server validation parity work in #1280 and #1281, which covered top-level positive limits but not these remaining bounds.

Fix

• validate query offsets and grouped-query sizes before local execution
• validate matrix limits and sample sizes for both response formats
• recursively validate limits across nested prefetch trees
• regenerate the async local client from the canonical sync implementation
• cover sync, async, batch-query, and nested-prefetch paths

Valid requests are unchanged. Invalid local requests now fail early with ValueError instead of returning misleading results.

Impact (X-Y-Z)

• X — before: 5 invalid-input classes were accepted across local query and matrix APIs.
• Y — after: all affected sync and async entry points reject those values before collection access, including batch and nested-prefetch dispatch.
• Z — coverage: 15 new regression assertions cover 8 sync cases and 7 async cases; the implementation adds only constant-time checks plus traversal of the already-provided prefetch tree.

Validation

• Python 3.10: focused sync/async regression suite (9 passed)
• Python 3.11: full in-memory suite (12 passed)
• conversion coverage suite (22 passed, 99% coverage)
• async-client generation consistency check
• mypy, pyright, local collection doctest, Ruff, and all pre-commit hooks

[netlify]

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

Name	Link
🔨 Latest commit	259e802
🔍 Latest deploy log	https://app.netlify.com/projects/poetic-froyo-8baba7/deploys/6a7f307cf2b7e20008c42607
😎 Deploy Preview	https://deploy-preview-1339--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: 91c3b565-4514-4a71-b014-5239d2c94e30

📥 Commits

Reviewing files that changed from the base of the PR and between f003e6c and 259e802.

📒 Files selected for processing (4)

• qdrant_client/local/async_qdrant_local.py
• qdrant_client/local/qdrant_local.py
• tests/test_async_qdrant_client.py
• tests/test_in_memory.py

---

📝 Walkthrough

Walkthrough

The local synchronous and asynchronous clients now validate nested prefetch limits, matrix-search limits and samples, query offsets, and grouped-query sizes. Validation occurs before query processing. In-memory and asynchronous tests cover invalid parameters and expected ValueError messages.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 259e8

The PR adds localized validation for invalid local query and matrix parameters while preserving valid requests; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: joein

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: validating local query parameters.
Description check	✅ Passed	The description directly explains the validation changes, affected APIs, rationale, tests, and validation results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ 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.}

[shashvat-singham]

Ran the branch — tests/test_in_memory.py is 12 passed, and I couldn't find a hole in the coverage.

Since the whole point here is matching server behaviour, I cross-checked each new bound against the validation attributes in lib/api/src/rest/schema.rs rather than assuming:

check	this PR	qdrant core
limit	< 1	#[validate(range(min = 1))]
sample	< 2	#[validate(range(min = 2))]
group_size	< 1	#[validate(range(min = 1))]
prefetch limit	< 1	#[validate(range(min = 1))]
offset	< 0	Option<usize>

All five line up. sample < 2 was the one I expected to be off — it's the only non-obvious constant — but core really does require min = 2, so it's right.

I also probed for paths the recursion might miss, and they're all covered:

batch: offset=-1           -> ValueError
batch: prefetch limit=0    -> ValueError
groups: prefetch limit=0   -> ValueError
nested prefetch limit=0    -> ValueError   # prefetch(limit=5, prefetch=prefetch(limit=0))
scroll(limit=0)            -> ValueError

The recursive _validate_prefetch_limits handling both the single-Prefetch and list[Prefetch] shapes is what makes the nested and batch cases work, and it's easy to get that wrong given prefetch is overloaded that way in the models.

One deliberate behaviour change worth calling out in the description: validation now runs before _get_collection, so query_points("missing", offset=-1) raises ValueError: offset value -1 is invalid where it previously raised collection-not-found. The tests encode that by using "missing" as the collection name. I think it's correct — the server validates the request body before it looks the collection up, so a 400 beats a 404 there, and it matches where the pre-existing limit < 1 check already sat — but it is a visible change for anyone catching the old error, so it's worth being explicit rather than leaving it implied by the test fixtures.

Nothing blocking from me.