fix(query): stop dropping zero-valued hybrid combination params - #819

Motivation

build_combination_method checks linear_alpha, rrf_constant and rrf_window for truthiness, so an explicit 0 is treated as if it were never passed. HybridQuery(..., combination_method="LINEAR", linear_alpha=0.0) raises ValueError: No parameters provided for combination method. With yield_combined_score_as set it raises nothing and sends no weights at all, so the server applies its defaults. rrf_constant=0 is replaced by the server's default of 60 without any signal, because HybridQuery always sends a window.

Changes

Treat 0 as a provided value

The three checks in build_combination_method now compare against None, so a 0 reaches the server:

HybridQuery(..., combination_method="LINEAR", linear_alpha=0.0)
# COMBINE LINEAR 4 ALPHA 0.0 BETA 1.0

HybridQuery(..., combination_method="RRF", rrf_constant=0)
# COMBINE RRF 4 WINDOW 20 CONSTANT 0

linear_alpha=0.0 scores by vector similarity only, the counterpart of linear_alpha=1.0. Redis rejects WINDOW 0, so rrf_window=0 now returns the server's WINDOW: Value below minimum error instead of silently running with a different window.

The linear_alpha docstring and the advanced queries notebook now say both searches still run at 0 and 1, so use VectorQuery or TextQuery when only one is needed.

Notes

build_base_query has similar truthiness checks on range_radius, range_epsilon and knn_ef_runtime. They are left out because they aren't combination params and need different handling: the server accepts RADIUS 0 but rejects EPSILON 0 and EF_RUNTIME 0.

Release Notes

HybridQuery now honours linear_alpha=0 and rrf_constant=0, including MCP search.params.linear_text_weight: 0 and rrf_constant: 0 on native hybrid search. These values were previously dropped, so affected queries will rank differently, and rrf_window=0 now returns a server error instead of being ignored.

Reviewer Brief

Start here: build_combination_method in redisvl/query/hybrid.py. It's the only production logic change, and sync, async and MCP hybrid search all go through it.

Where it could fail

• redisvl/query/hybrid.py:337: a query or MCP config passing rrf_window=0 used to run and now gets a server error; nothing in the repo passes it.

Not verified: a full MCP server run with these values (only the query arguments it builds); Redis Cluster, Redis Software and Redis Cloud. The docs don't state whether 0 is accepted for ALPHA or CONSTANT, so that rests on the runs against Redis 8.4.8 and 8.10.3. The cost difference from VectorQuery and TextQuery wasn't measured; the runs only confirm both searches still execute at alpha 0 and 1.

Beyond CI: reverting each of the three checks on its own fails only the regression tests for that parameter; the tests also pass on redis-py 7.1.0 and 7.4.1.

Since the last brief: f91c0a4 consolidates the zero-value tests and makes the test_hybrid_query_alpha assertion two-sided; 3feccd1 documents that both searches run at alpha 0 and 1. No production logic changed.

_{Reviewed fd4bc4c · Claude Code (claude-opus-5-5) · lenses: correctness, security, design, tests, docs, Redis behaviour}