Skip to content

feat: per-request HNSW ef via vector_search_params on vector and hybrid searches - #2268

Open
rlmanrique wants to merge 2 commits into
mainfrom
feat/per-request-ef
Open

rlmanrique wants to merge 2 commits into
mainfrom
feat/per-request-ef

Conversation

@rlmanrique

Copy link
Copy Markdown
Contributor

Motivation

weaviate/weaviate#13947 (open, unreleased; targets 1.41) adds a per-request HNSW ef to the gRPC SearchRequest as vector_search_params { ef } (field 63, with field 2 of the params message reserved for a future HFresh search_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 as vector_search_params=VectorSearchParams(ef=...).

Server contract (all enforced server-side): unset or 0 means the collection's configured ef / dynamic ef; the server floors the value at k (max(ef, limit)), so a small ef never truncates results; values above HNSW_MAX_SEARCH_EF (default QUERY_MAXIMUM_RESULTS, 10000) return InvalidArgument; 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

  • One public input type, VectorSearchParams (exported from weaviate.classes.query), rather than a bare ef kwarg, so the next knob (search_probe) becomes a field instead of another fan-out across every overload. It is strict (ef must be a non-negative int; bool/str/float and unknown fields are rejected) because the wire type is uint32 and lax coercion would hide typos.
  • One mapping point in _QueryGRPC.__create_request. None leaves the proto field unset, so a request without the option is byte-identical to before; VectorSearchParams() sends an empty message and ef=0 is sent as 0, both of which the server reads as "collection default".
  • No client-side semantics beyond types: flooring, the cap and the bm25 rule stay on the server. An over-cap value surfaces as WeaviateQueryError.
  • Offered on near_vector, near_object, near_text, near_image, near_media and hybrid in both collection.query and collection.generate. Not offered on bm25 (the server rejects it) or fetch_objects.
  • Server-version gate, following the precedent of BM25Operator.and_cross() and query profiling: passing the option to a server below 1.41.0 raises WeaviateUnsupportedFeatureError instead of silently searching with the collection ef (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.
  • gRPC stubs regenerated with the repo's weaviate/proto/v1/regen.sh against the server branch (claude/specify-ef-search-feature-68e610, commit c1972f1c) for all three protobuf runtimes. The script takes a local checkout, so the branch's grpc/proto directory was exported and pointed at; no release tag was needed. This also syncs BatchDeleteReply.limit, already on server main and unread by client code.
  • .pyi stubs regenerated with tools/stubs_regen.sh.

Testing

  • test/collection/test_vector_search_params.py (41 cases): parametrized over every entry point; field present exactly when passed; None byte-identical to omitting; empty params and ef=0 wire shapes; ef below limit sent unchanged; other fields untouched; type and sign validation; bm25/get reject the kwarg; version gate (1.40.2 rejected, 1.41.0-rc.0 accepted).
  • mock_tests/test_vector_search_params.py (5 cases): through collection.query / collection.generate against a gRPC stub capturing the SearchRequest, 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=1 with limit=10 still returns 10 and matches the default-ef set; high ef matches default ordering; near_object, hybrid and near_text accept it; ef=10_000_001 raises with HNSW_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 full test, mock_tests and proto_test suites pass locally.

Notes for the release

  • Do not merge before feat(search): per-request HNSW ef via vectorSearchParams on gRPC and REST /v1/search weaviate#13947 lands; if the field moves, re-run weaviate/proto/v1/regen.sh against the merged commit.
  • No changelog entry here, per RELEASING.md. Suggested wording: Add vector_search_params=VectorSearchParams(ef=...) to near_vector, near_object, near_text, near_image, near_media and hybrid in collection.query and collection.generate to override the collection's HNSW ef for a single request (Weaviate 1.41+); unset keeps the collection default, flat and HFresh indexes ignore it, and it is not offered on bm25.

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.

…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).

@orca-security-eu orca-security-eu Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Orca Security Scan Summary

Status Check Issues by priority
Passed Passed Infrastructure as Code high 0   medium 0   low 0   info 0 View in Orca
Passed Passed SAST high 0   medium 0   low 0   info 0 View in Orca
Passed Passed Secrets high 0   medium 0   low 0   info 0 View in Orca
Passed Passed Vulnerabilities high 0   medium 0   low 0   info 0 View in Orca

@codecov-commenter

Copy link
Copy Markdown

⚠️ Please install the 'codecov app svg image' to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 86.66667% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.65%. Comparing base (635124c) to head (5a5a17c).
⚠️ Report is 49 commits behind head on main.

Files with missing lines Patch % Lines
...ntegration/test_collection_vector_search_params.py 52.72% 26 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.
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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants