feat: Add runtime parameter support for HNSW and SVS-VAMANA vector indexes #439
Conversation
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
…dexes Add comprehensive runtime parameter support for HNSW and SVS-VAMANA vector indexes across VectorQuery, VectorRangeQuery, and AggregateHybridQuery classes. Runtime parameters allow users to tune search performance at query time without rebuilding indexes, enabling dynamic trade-offs between accuracy and speed. Changes: - Add HNSW runtime parameters: ef_runtime, epsilon - Add SVS-VAMANA runtime parameters: search_window_size, epsilon, use_search_history, search_buffer_capacity - Implement setter methods with validation for all parameters - Add runtime parameter constants to BaseVectorQuery and AggregateHybridQuery - Update query string generation to include runtime parameters - Fix type annotation for params dict in AggregateHybridQuery Documentation: - Update API reference docs (query.rst, schema.rst) - Add runtime parameters section to SVS-VAMANA tutorial (09_svs_vamana.ipynb) - Add runtime parameters section to advanced queries tutorial (11_advanced_queries.ipynb) - Add runtime parameters notes to getting started and hybrid queries tutorials - Update README.md with ef_runtime example Tests: - Add tests for runtime parameters across all query types - Test parameter validation and error handling - Test query string generation with runtime parameters - Test parameter combinations
nkanu17
requested review from
Copilot and
justin-cechmanek
and removed request for
Copilot
nkanu17
requested review from
abrookins,
bsbodden,
hanchoong-redis and
rbs333
Copilot finished reviewing on behalf of
nkanu17
November 21, 2025 20:55
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive runtime parameter support for HNSW and SVS-VAMANA vector indexes, enabling users to tune search performance at query time without rebuilding indexes. The implementation adds parameters across three query types: VectorQuery, VectorRangeQuery, and AggregateHybridQuery.
Key changes:
- Added runtime parameters (
ef_runtime,epsilon,search_window_size,use_search_history,search_buffer_capacity) to VectorQuery with validation - Added SVS-VAMANA parameters (
search_window_size,use_search_history,search_buffer_capacity) to VectorRangeQuery - Added all runtime parameters to AggregateHybridQuery for hybrid search tuning
- Updated documentation across API references, user guides, and README with examples
Reviewed changes
Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| redisvl/query/query.py | Implemented runtime parameters in BaseVectorQuery, VectorQuery, and VectorRangeQuery with validation methods, properties, and query string generation |
| redisvl/query/aggregate.py | Added runtime parameter constants and support to AggregateHybridQuery for HNSW and SVS-VAMANA tuning |
| tests/unit/test_query_types.py | Added comprehensive tests for all runtime parameters including validation, query string generation, and parameter combinations |
| tests/unit/test_aggregation_types.py | Added tests for runtime parameters in AggregateHybridQuery |
| docs/api/query.rst | Added runtime parameter documentation and examples for VectorQuery, VectorRangeQuery, and AggregateHybridQuery |
| docs/api/schema.rst | Updated HNSW and SVS-VAMANA sections with runtime parameter details and clarified index-time vs query-time parameters |
| docs/user_guide/09_svs_vamana.ipynb | Added comprehensive section on runtime parameters with examples for both KNN and range queries |
| docs/user_guide/11_advanced_queries.ipynb | Added runtime parameters section with examples for HNSW and SVS-VAMANA in hybrid queries |
| docs/user_guide/02_hybrid_queries.ipynb | Added performance tip note about runtime parameters with example code |
| docs/user_guide/01_getting_started.ipynb | Added note about runtime parameters with example code |
| README.md | Updated VectorQuery example to include ef_runtime parameter |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…ooks from CI Exclude these notebooks to isolate CI failures: - 09_svs_vamana.ipynb (runtime parameters examples) - 11_advanced_queries.ipynb (AggregateHybridQuery changes) Will re-enable incrementally to identify which notebook is causing failures.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Re-enable SVS-VAMANA notebook testing (only on Redis 8.2+). Still excluding 11_advanced_queries.ipynb to isolate any issues. Testing incrementally to identify which notebook causes CI failures.
Re-enable advanced queries notebook testing. Restore Makefile to original state - all notebooks now tested. Both 09_svs_vamana.ipynb and 11_advanced_queries.ipynb confirmed working.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 11 out of 11 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…T.AGGREGATE AggregateHybridQuery uses FT.AGGREGATE commands which do NOT support runtime parameters. Runtime parameters (ef_runtime for HNSW, search_window_size for SVS-VAMANA) only work with FT.SEARCH commands (VectorQuery, VectorRangeQuery). Changes: - Removed ef_runtime parameter from AggregateHybridQuery.__init__() - Removed EF_RUNTIME and EF_RUNTIME_PARAM constants - Removed ef_runtime handling from params property and _build_query_string() - Removed test_aggregate_hybrid_query_ef_runtime() test - Updated docs/api/query.rst to clarify no runtime parameters are supported - Removed ef_runtime example from docs/user_guide/11_advanced_queries.ipynb - Updated notebook to explain runtime parameters only work with VectorQuery This fixes CI failures where ef_runtime was causing 'Invalid option' errors when used with FT.AGGREGATE commands.
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.
Add Runtime Parameter Support for Vector Queries
Related to #433
What's New
Adds runtime parameter support for HNSW and SVS-VAMANA vector indexes to
VectorQueryandVectorRangeQuery.New Parameters
VectorQuery & VectorRangeQuery
HNSW:
ef_runtime- Tune search accuracy (higher = better recall, slower)epsilon- Range search boundary factor (VectorRangeQuery only)SVS-VAMANA:
search_window_size- KNN search window sizeuse_search_history- Search buffer control (OFF/ON/AUTO)search_buffer_capacity- 2-level compression tuningepsilon- Range search approximation (VectorRangeQuery only)AggregateHybridQuery
❌ No runtime parameters (FT.AGGREGATE doesn't support them)
Example
Breaking Changes
None (for users upgrading from main)