Repository navigation
feat: per-request HNSW ef via vector_search_params on vector and hybrid searches - #2268
Open
rlmanrique wants to merge 2 commits into
Open
rlmanrique wants to merge 2 commits into
rlmanrique wants to merge 2 commits into
Conversation
…arch_params Generated with weaviate/proto/v1/regen.sh against weaviate/weaviate branch claude/specify-ef-search-feature-68e610 (c1972f1c), for the v4216, v5261 and v6300 protobuf runtimes. Besides the new VectorSearchParams message this picks up BatchDeleteReply.limit, which server main already has and the client did not read.
… searches Expose the per-request ef added by weaviate/weaviate#13947 as vector_search_params=VectorSearchParams(ef=...) on near_vector, near_object, near_text, near_image, near_media and hybrid in collection.query and collection.generate. None leaves the request unchanged; an empty params object or ef=0 means the collection default; the server floors ef at the limit and enforces HNSW_MAX_SEARCH_EF. The option is not offered on bm25 or fetch_objects, where the server rejects or ignores it, and raises WeaviateUnsupportedFeatureError on servers below 1.41.0, which would otherwise drop the unknown field silently. Unit tests cover the request builder for every entry point, mock tests the public API against a request-capturing gRPC stub, and integration tests the server behaviour (they skip below 1.41.0).
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
| Infrastructure as Code | View in Orca | ||
| SAST | View in Orca | ||
| Secrets | View in Orca | ||
| Vulnerabilities | View in Orca |
|
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #2268 +/- ##
==========================================
+ Coverage 89.23% 89.65% +0.42%
==========================================
Files 312 318 +6
Lines 24715 25170 +455
==========================================
+ Hits 22055 22567 +512
+ Misses 2660 2603 -57 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
weaviate/weaviate#13947 (open, unreleased; targets 1.41) adds a per-request HNSW
efto the gRPCSearchRequestasvector_search_params { ef }(field 63, with field 2 of the params message reserved for a future HFreshsearch_probe). A single query can then trade recall for latency without a collection-wide schema update: an interactive path and an offline high-recall evaluation can hit the same collection with different beam widths. This PR exposes it in the v4 collections API asvector_search_params=VectorSearchParams(ef=...).Server contract (all enforced server-side): unset or
0means the collection's configuredef/ dynamic ef; the server floors the value atk(max(ef, limit)), so a smallefnever truncates results; values aboveHNSW_MAX_SEARCH_EF(defaultQUERY_MAXIMUM_RESULTS, 10000) returnInvalidArgument; it applies to near_vector, near_object, near_text, near_image/near_media, hybrid (dense leg) and multi-target searches; flat and HFresh indexes ignore it; a bm25-only request with the field set is rejected.Approach
VectorSearchParams(exported fromweaviate.classes.query), rather than a bareefkwarg, so the next knob (search_probe) becomes a field instead of another fan-out across every overload. It is strict (efmust be a non-negativeint; bool/str/float and unknown fields are rejected) because the wire type isuint32and lax coercion would hide typos._QueryGRPC.__create_request.Noneleaves the proto field unset, so a request without the option is byte-identical to before;VectorSearchParams()sends an empty message andef=0is sent as0, both of which the server reads as "collection default".WeaviateQueryError.near_vector,near_object,near_text,near_image,near_mediaandhybridin bothcollection.queryandcollection.generate. Not offered onbm25(the server rejects it) orfetch_objects.BM25Operator.and_cross()and query profiling: passing the option to a server below 1.41.0 raisesWeaviateUnsupportedFeatureErrorinstead of silently searching with the collectionef(older servers drop the unknown field). The minimum lives in one constant,_VECTOR_SEARCH_PARAMS_MIN_VERSION, and should be confirmed against the release that ships the server PR.weaviate/proto/v1/regen.shagainst the server branch (claude/specify-ef-search-feature-68e610, commitc1972f1c) for all three protobuf runtimes. The script takes a local checkout, so the branch'sgrpc/protodirectory was exported and pointed at; no release tag was needed. This also syncsBatchDeleteReply.limit, already on server main and unread by client code..pyistubs regenerated withtools/stubs_regen.sh.Testing
test/collection/test_vector_search_params.py(41 cases): parametrized over every entry point; field present exactly when passed;Nonebyte-identical to omitting; empty params andef=0wire shapes;efbelowlimitsent unchanged; other fields untouched; type and sign validation;bm25/getreject the kwarg; version gate (1.40.2 rejected, 1.41.0-rc.0 accepted).mock_tests/test_vector_search_params.py(5 cases): throughcollection.query/collection.generateagainst a gRPC stub capturing theSearchRequest, plus the gate against the shared 1.36 mock.integration/test_collection_vector_search_params.py(7 cases): run locally against the server PR's preview image (1.41.0-rc.0):ef=1withlimit=10still returns 10 and matches the default-ef set; highefmatches default ordering; near_object, hybrid and near_text accept it;ef=10_000_001raises withHNSW_MAX_SEARCH_EF; flat index ignores it. CI pins Weaviate 1.40.2, so these auto-skip until the matrix includes a release with the feature.ruff check,ruff format --diff,flake8,pyright(weaviate and integration folders) and the fulltest,mock_testsandproto_testsuites pass locally.Notes for the release
weaviate/proto/v1/regen.shagainst the merged commit.vector_search_params=VectorSearchParams(ef=...)tonear_vector,near_object,near_text,near_image,near_mediaandhybridincollection.queryandcollection.generateto override the collection's HNSWeffor a single request (Weaviate 1.41+); unset keeps the collection default, flat and HFresh indexes ignore it, and it is not offered onbm25.Breaking changes
None. The new argument is keyword-only and optional; requests that do not pass it are unchanged. New public export:
weaviate.classes.query.VectorSearchParams.