Use full query num_results for KNN; set parameter defaults

Author: vishal-bala

redisvl/query/hybrid.py

@@ -52,19 +52,18 @@ def __init__(
         text_scorer: str = "BM25STD",
         yield_text_score_as: Optional[str] = None,
         vector_search_method: Optional[Literal["KNN", "RANGE"]] = None,
-        knn_num_results: Optional[int] = None,
-        knn_ef_runtime: Optional[int] = None,
-        range_radius: Optional[int] = None,
-        range_epsilon: Optional[float] = None,
+        knn_ef_runtime: int = 10,
+        range_radius: Optional[float] = None,
+        range_epsilon: float = 0.01,
         yield_vsim_score_as: Optional[str] = None,
         filter_expression: Optional[Union[str, FilterExpression]] = None,
         combination_method: Optional[Literal["RRF", "LINEAR"]] = None,
-        rrf_window: Optional[int] = None,
-        rrf_constant: Optional[float] = None,
-        linear_alpha: Optional[float] = None,
+        rrf_window: int = 20,
+        rrf_constant: int = 60,
+        linear_alpha: float = 0.3,
         yield_combined_score_as: Optional[str] = None,
         dtype: str = "float32",
-        num_results: Optional[int] = None,
+        num_results: Optional[int] = 10,
         return_fields: Optional[List[str]] = None,
         stopwords: Optional[Union[str, Set[str]]] = "english",
         text_weights: Optional[Dict[str, float]] = None,
@@ -83,7 +82,6 @@ def __init__(
                 see https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/scoring/
             yield_text_score_as: The name of the field to yield the text score as.
             vector_search_method: The vector search method to use. Options are {KNN, RANGE}. Defaults to None.
-            knn_num_results: The number of nearest neighbors to return, required if `vector_search_method` is "KNN".
             knn_ef_runtime: The exploration factor parameter for HNSW, optional if `vector_search_method` is "KNN".
             range_radius: The search radius to use, required if `vector_search_method` is "RANGE".
             range_epsilon: The epsilon value to use, optional if `vector_search_method` is "RANGE"; defines the
@@ -98,10 +96,10 @@ def __init__(
                 fusion scope.
             rrf_constant: The constant to use for the reciprocal rank fusion (RRF) combination method. Controls decay
                 of rank influence.
-            linear_alpha: The weight of the first query for the linear combination method (LINEAR).
+            linear_alpha: The weight of the text query for the linear combination method (LINEAR).
             yield_combined_score_as: The name of the field to yield the combined score as.
             dtype: The data type of the vector. Defaults to "float32".
-            num_results: The number of results to return. If not specified, the server default will be used (10).
+            num_results: The number of results to return.
             return_fields: The fields to return. Defaults to None.
             stopwords (Optional[Union[str, Set[str]]], optional): The stopwords to remove from the
                 provided text prior to search-use. If a string such as "english" "german" is
@@ -155,7 +153,7 @@ def __init__(
             text_scorer=text_scorer,
             yield_text_score_as=yield_text_score_as,
             vector_search_method=vector_search_method,
-            knn_num_results=knn_num_results,
+            num_results=num_results,
             knn_ef_runtime=knn_ef_runtime,
             range_radius=range_radius,
             range_epsilon=range_epsilon,
@@ -185,9 +183,9 @@ def build_base_query(
     text_scorer: str = "BM25STD",
     yield_text_score_as: Optional[str] = None,
     vector_search_method: Optional[Literal["KNN", "RANGE"]] = None,
-    knn_num_results: Optional[int] = None,
+    num_results: Optional[int] = None,
     knn_ef_runtime: Optional[int] = None,
-    range_radius: Optional[int] = None,
+    range_radius: Optional[float] = None,
     range_epsilon: Optional[float] = None,
     yield_vsim_score_as: Optional[str] = None,
     filter_expression: Optional[Union[str, FilterExpression]] = None,
@@ -205,7 +203,7 @@ def build_base_query(
             see https://redis.io/docs/latest/develop/ai/search-and-query/advanced-concepts/scoring/
         yield_text_score_as: The name of the field to yield the text score as.
         vector_search_method: The vector search method to use. Options are {KNN, RANGE}. Defaults to None.
-        knn_num_results: The number of nearest neighbors to return, required if `vector_search_method` is "KNN".
+        num_results: The number of nearest neighbors to return, required if `vector_search_method` is "KNN".
         knn_ef_runtime: The exploration factor parameter for HNSW, optional if `vector_search_method` is "KNN".
         range_radius: The search radius to use, required if `vector_search_method` is "RANGE".
         range_epsilon: The epsilon value to use, optional if `vector_search_method` is "RANGE"; defines the
@@ -254,12 +252,12 @@ def build_base_query(
     vsim_search_method_params: Dict[str, Any] = {}
     if vector_search_method == "KNN":
         vsim_search_method = VectorSearchMethods.KNN
-        if not knn_num_results:
+        if not num_results:
             raise ValueError(
-                "Must provide `knn_num_results` if vector_search_method is KNN"
+                "Must provide `num_results` if vector_search_method is KNN"
             )
 
-        vsim_search_method_params["K"] = knn_num_results
+        vsim_search_method_params["K"] = num_results
         if knn_ef_runtime:
             vsim_search_method_params["EF_RUNTIME"] = knn_ef_runtime
 

tests/integration/test_hybrid.py

@@ -136,7 +136,7 @@ def test_hybrid_query(index):
 
     results = index.query(hybrid_query)
     assert isinstance(results, list)
-    assert len(results) == 10  # Server-side default for hybrid search
+    assert len(results) == 10  # default for hybrid search
     for doc in results:
         assert doc["user"] in [
             "john",

tests/unit/test_hybrid_types.py

@@ -77,6 +77,9 @@ def test_hybrid_query_basic_initialization():
         "VSIM",
         "@embedding",
         bytes_vector,
+        "LIMIT",
+        "0",
+        "10",
     ]
 
     # Verify that no combination method is set
@@ -97,16 +100,16 @@ def test_hybrid_query_with_all_parameters():
         text_scorer="TFIDF",
         yield_text_score_as="text_score",
         vector_search_method="KNN",
-        knn_num_results=10,
         knn_ef_runtime=100,
         yield_vsim_score_as="vsim_score",
         filter_expression=filter_expression,
         stopwords=None,
         text_weights=text_weights,
         combination_method="RRF",
         rrf_window=10,
-        rrf_constant=0.5,
+        rrf_constant=50,
         yield_combined_score_as="hybrid_score",
+        num_results=10,
     )
 
     assert hybrid_query._ft_helper is not None
@@ -140,9 +143,12 @@ def test_hybrid_query_with_all_parameters():
         "WINDOW",
         10,
         "CONSTANT",
-        0.5,
+        50,
         "YIELD_SCORE_AS",
         "hybrid_score",
+        "LIMIT",
+        "0",
+        "10",
     ]
 
     # Add post-processing and verify that it is reflected in the query
@@ -373,6 +379,9 @@ def test_hybrid_query_with_string_filter():
         bytes_vector,
         "FILTER",
         "@category:{tech|science|engineering}",
+        "LIMIT",
+        "0",
+        "10",
     ]
 
 
@@ -399,6 +408,9 @@ def test_hybrid_query_with_tag_filter():
         bytes_vector,
         "FILTER",
         "@genre:{comedy}",
+        "LIMIT",
+        "0",
+        "10",
     ]
 
 
@@ -506,28 +518,18 @@ def test_hybrid_query_without_filter():
 @pytest.mark.skipif(not REDIS_HYBRID_AVAILABLE, reason=SKIP_REASON)
 def test_hybrid_query_vector_search_method_knn():
     """Test HybridQuery with KNN vector search method."""
-    with pytest.raises(ValueError):
-        # KNN requires K
-        HybridQuery(
-            text=sample_text,
-            text_field_name="description",
-            vector=sample_vector,
-            vector_field_name="embedding",
-            vector_search_method="KNN",
-        )
-
     hybrid_query = HybridQuery(
         text=sample_text,
         text_field_name="description",
         vector=sample_vector,
         vector_field_name="embedding",
         vector_search_method="KNN",
-        knn_num_results=10,
+        num_results=10,
     )
 
     # KNN with params should be in args
     args = get_query_pieces(hybrid_query)
-    assert args[-4:] == ["KNN", 2, "K", 10]
+    assert args[7:13] == ["KNN", 4, "K", 10, "EF_RUNTIME", 10]
 
     # With optional EF_RUNTIME param
     hybrid_query = HybridQuery(
@@ -536,13 +538,13 @@ def test_hybrid_query_vector_search_method_knn():
         vector=sample_vector,
         vector_field_name="embedding",
         vector_search_method="KNN",
-        knn_num_results=10,
         knn_ef_runtime=100,
+        num_results=10,
     )
 
     # KNN with params should be in args
     args = get_query_pieces(hybrid_query)
-    assert args[-6:] == ["KNN", 4, "K", 10, "EF_RUNTIME", 100]
+    assert args[7:13] == ["KNN", 4, "K", 10, "EF_RUNTIME", 100]
 
 
 @pytest.mark.skipif(not REDIS_HYBRID_AVAILABLE, reason=SKIP_REASON)
@@ -569,7 +571,7 @@ def test_hybrid_query_vector_search_method_range():
 
     # RANGE with params should be in args
     args = get_query_pieces(hybrid_query)
-    assert args[-4:] == ["RANGE", 2, "RADIUS", 10]
+    assert args[7:13] == ["RANGE", 4, "RADIUS", 10, "EPSILON", 0.01]
 
     # With optional EPSILON param
     hybrid_query = HybridQuery(
@@ -584,7 +586,7 @@ def test_hybrid_query_vector_search_method_range():
 
     # RANGE with params should be in args
     args = get_query_pieces(hybrid_query)
-    assert args[-6:] == ["RANGE", 4, "RADIUS", 10, "EPSILON", 0.1]
+    assert args[7:13] == ["RANGE", 4, "RADIUS", 10, "EPSILON", 0.1]
 
 
 @pytest.mark.skipif(not REDIS_HYBRID_AVAILABLE, reason=SKIP_REASON)
@@ -644,6 +646,9 @@ def test_hybrid_query_special_characters_in_text():
         "VSIM",
         "@embedding",
         bytes_vector,
+        "LIMIT",
+        "0",
+        "10",
     ]
 
 
@@ -668,6 +673,9 @@ def test_hybrid_query_unicode_text():
         "VSIM",
         "@embedding",
         bytes_vector,
+        "LIMIT",
+        "0",
+        "10",
     ]
 
 
@@ -682,13 +690,22 @@ def test_hybrid_query_with_vector_filter_and_method():
         vector=sample_vector,
         vector_field_name="embedding",
         vector_search_method="KNN",
-        knn_num_results=10,
         filter_expression=tag_filter,
+        num_results=10,
     )
 
     # Verify KNN params and filter are both in args
     args = get_query_pieces(hybrid_query)
-    assert args[-6:] == ["KNN", 2, "K", 10, "FILTER", "@genre:{comedy}"]
+    assert args[7:15] == [
+        "KNN",
+        4,
+        "K",
+        10,
+        "EF_RUNTIME",
+        10,
+        "FILTER",
+        "@genre:{comedy}",
+    ]
 
 
 # Combination method tests
@@ -713,9 +730,11 @@ def test_hybrid_query_combination_method_rrf_basic():
     assert hybrid_query.combination_method.get_args() == [
         "COMBINE",
         "RRF",
-        2,
+        4,
         "WINDOW",
         10,
+        "CONSTANT",
+        60,
     ]
 
 
@@ -728,7 +747,7 @@ def test_hybrid_query_combination_method_rrf_with_constant():
         vector=sample_vector,
         vector_field_name="embedding",
         combination_method="RRF",
-        rrf_constant=0.5,
+        rrf_constant=50,
     )
 
     # Verify RRF combination method is set
@@ -738,9 +757,11 @@ def test_hybrid_query_combination_method_rrf_with_constant():
     assert hybrid_query.combination_method.get_args() == [
         "COMBINE",
         "RRF",
-        2,
+        4,
+        "WINDOW",
+        20,
         "CONSTANT",
-        0.5,
+        50,
     ]
 
 
@@ -754,7 +775,7 @@ def test_hybrid_query_combination_method_rrf_with_both_params():
         vector_field_name="embedding",
         combination_method="RRF",
         rrf_window=20,
-        rrf_constant=1.0,
+        rrf_constant=50,
         yield_combined_score_as="rrf_score",
     )
 
@@ -769,7 +790,7 @@ def test_hybrid_query_combination_method_rrf_with_both_params():
         "WINDOW",
         20,
         "CONSTANT",
-        1.0,
+        50,
         "YIELD_SCORE_AS",
         "rrf_score",
     ]