Implement scan_factor and max_candidates for query

pinecone/core/grpc/protos/db_data_2025_10_pb2.pyi

@@ -200,6 +200,8 @@ class QueryRequest(_message.Message):
     VECTOR_FIELD_NUMBER: _ClassVar[int]
     SPARSE_VECTOR_FIELD_NUMBER: _ClassVar[int]
     ID_FIELD_NUMBER: _ClassVar[int]
+    SCAN_FACTOR_FIELD_NUMBER: _ClassVar[int]
+    MAX_CANDIDATES_FIELD_NUMBER: _ClassVar[int]
     namespace: str
     top_k: int
     filter: _struct_pb2.Struct
@@ -209,7 +211,9 @@ class QueryRequest(_message.Message):
     vector: _containers.RepeatedScalarFieldContainer[float]
     sparse_vector: SparseValues
     id: str
-    def __init__(self, namespace: _Optional[str] = ..., top_k: _Optional[int] = ..., filter: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., include_values: _Optional[bool] = ..., include_metadata: _Optional[bool] = ..., queries: _Optional[_Iterable[_Union[QueryVector, _Mapping]]] = ..., vector: _Optional[_Iterable[float]] = ..., sparse_vector: _Optional[_Union[SparseValues, _Mapping]] = ..., id: _Optional[str] = ...) -> None: ...
+    scan_factor: float
+    max_candidates: int
+    def __init__(self, namespace: _Optional[str] = ..., top_k: _Optional[int] = ..., filter: _Optional[_Union[_struct_pb2.Struct, _Mapping]] = ..., include_values: _Optional[bool] = ..., include_metadata: _Optional[bool] = ..., queries: _Optional[_Iterable[_Union[QueryVector, _Mapping]]] = ..., vector: _Optional[_Iterable[float]] = ..., sparse_vector: _Optional[_Union[SparseValues, _Mapping]] = ..., id: _Optional[str] = ..., scan_factor: _Optional[float] = ..., max_candidates: _Optional[int] = ...) -> None: ...
 
 class SingleQueryResults(_message.Message):
     __slots__ = ()

pinecone/core/openapi/db_data/model/query_request.py

@@ -80,6 +80,8 @@ class QueryRequest(ModelNormal):
         ("queries",): {},
         ("vector",): {},
         ("id",): {"max_length": 512},
+        ("scan_factor",): {"inclusive_maximum": 4.0, "inclusive_minimum": 0.5},
+        ("max_candidates",): {"inclusive_maximum": 100000, "inclusive_minimum": 1},
     }
 
     @cached_class_property
@@ -114,6 +116,8 @@ def openapi_types(cls):
             "vector": ([float],),  # noqa: E501
             "sparse_vector": (SparseValues,),  # noqa: E501
             "id": (str,),  # noqa: E501
+            "scan_factor": (float,),  # noqa: E501
+            "max_candidates": (int,),  # noqa: E501
         }
 
     @cached_class_property
@@ -130,6 +134,8 @@ def discriminator(cls):
         "vector": "vector",  # noqa: E501
         "sparse_vector": "sparseVector",  # noqa: E501
         "id": "id",  # noqa: E501
+        "scan_factor": "scanFactor",  # noqa: E501
+        "max_candidates": "maxCandidates",  # noqa: E501
     }
 
     read_only_vars: Set[str] = set([])
@@ -194,6 +200,8 @@ def _from_openapi_data(cls: Type[T], top_k, *args, **kwargs) -> T:  # noqa: E501
             vector ([float]): The query vector. This should be the same length as the dimension of the index being queried. Each `query` request can contain only one of the parameters `id` or `vector`. [optional]  # noqa: E501
             sparse_vector (SparseValues): [optional]  # noqa: E501
             id (str): The unique ID of the vector to be used as a query vector. Each request  can contain either the `vector` or `id` parameter. [optional]  # noqa: E501
+            scan_factor (float): An optimization parameter for IVF dense indexes in dedicated read node indexes. It adjusts how much of the index is scanned to find vector candidates. Range: 0.5 – 4 (default). Keep the default (4.0) for the best search results. If query latency is too high, try lowering this value incrementally (minimum 0.5) to speed up the search at the cost of slightly lower accuracy. This parameter is only supported for dedicated (DRN) dense indexes.  [optional]  # noqa: E501
+            max_candidates (int): An optimization parameter that controls the maximum number of candidate dense vectors to rerank. Reranking computes exact distances to improve recall but increases query latency. Range: top_k – 100000. Keep the default for a balance of recall and latency. Increase this value if recall is too low, or decrease it to reduce latency at the cost of accuracy. This parameter is only supported for dedicated (DRN) dense indexes. [optional]  # noqa: E501
         """
 
         _enforce_allowed_values = kwargs.pop("_enforce_allowed_values", False)
@@ -295,6 +303,8 @@ def __init__(self, top_k, *args, **kwargs) -> None:  # noqa: E501
             vector ([float]): The query vector. This should be the same length as the dimension of the index being queried. Each `query` request can contain only one of the parameters `id` or `vector`. [optional]  # noqa: E501
             sparse_vector (SparseValues): [optional]  # noqa: E501
             id (str): The unique ID of the vector to be used as a query vector. Each request  can contain either the `vector` or `id` parameter. [optional]  # noqa: E501
+            scan_factor (float): An optimization parameter for IVF dense indexes in dedicated read node indexes. It adjusts how much of the index is scanned to find vector candidates. Range: 0.5 – 4 (default). Keep the default (4.0) for the best search results. If query latency is too high, try lowering this value incrementally (minimum 0.5) to speed up the search at the cost of slightly lower accuracy. This parameter is only supported for dedicated (DRN) dense indexes.  [optional]  # noqa: E501
+            max_candidates (int): An optimization parameter that controls the maximum number of candidate dense vectors to rerank. Reranking computes exact distances to improve recall but increases query latency. Range: top_k – 100000. Keep the default for a balance of recall and latency. Increase this value if recall is too low, or decrease it to reduce latency at the cost of accuracy. This parameter is only supported for dedicated (DRN) dense indexes. [optional]  # noqa: E501
         """
 
         _enforce_allowed_values = kwargs.pop("_enforce_allowed_values", True)

pinecone/db_data/index.py

@@ -945,6 +945,8 @@ def query(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: SparseValues | SparseVectorTypedDict | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> QueryResponse | ApplyResult:
         """Query a namespace using a query vector.
@@ -970,6 +972,14 @@ def query(
             sparse_vector: Sparse values of the query vector. Expected to be either a SparseValues object or a dict
                           of the form: ``{'indices': list[int], 'values': list[float]}``, where the lists each have
                           the same length. [optional]
+            scan_factor: An optimization parameter for the IVF dense indexes in dedicated
+                        read node indexes. It adjusts how much of the index is scanned to find
+                        vector candidates. Range: 0.5 - 4 (default). This parameter is only
+                        supported for dedicated (DRN) dense indexes. [optional]
+            max_candidates: An optimization parameter that controls the maximum number of
+                           candidate dense vectors to rerank. Reranking computes exact distances to
+                           improve recall but increases query latency. Range: top_k - 100000. This
+                           parameter is only supported for dedicated (DRN) dense indexes. [optional]
             **kwargs: Additional keyword arguments for the API call.
 
         Returns:
@@ -1033,6 +1043,8 @@ def query(
             include_values=include_values,
             include_metadata=include_metadata,
             sparse_vector=sparse_vector,
+            scan_factor=scan_factor,
+            max_candidates=max_candidates,
             **kwargs,
         )
 
@@ -1054,6 +1066,8 @@ def _query(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: SparseValues | SparseVectorTypedDict | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> OpenAPIQueryResponse:
         if len(args) > 0:
@@ -1073,6 +1087,8 @@ def _query(
             include_values=include_values,
             include_metadata=include_metadata,
             sparse_vector=sparse_vector,
+            scan_factor=scan_factor,
+            max_candidates=max_candidates,
             **kwargs,
         )
         from typing import cast
@@ -1092,6 +1108,8 @@ def query_namespaces(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: SparseValues | SparseVectorTypedDict | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> QueryNamespacesResults:
         """Query multiple namespaces in parallel and combine the results.
@@ -1116,6 +1134,14 @@ def query_namespaces(
             include_values: Boolean field indicating whether vector values should be included with results. Defaults to None. [optional]
             include_metadata: Boolean field indicating whether vector metadata should be included with results. Defaults to None. [optional]
             sparse_vector: If you are working with a dotproduct index, you can pass a sparse vector as part of your hybrid search. Defaults to None. [optional]
+            scan_factor: An optimization parameter for the IVF dense indexes in dedicated
+                        read node indexes. It adjusts how much of the index is scanned to find
+                        vector candidates. Range: 0.5 - 4 (default). This parameter is only
+                        supported for dedicated (DRN) dense indexes. [optional]
+            max_candidates: An optimization parameter that controls the maximum number of
+                           candidate dense vectors to rerank. Reranking computes exact distances to
+                           improve recall but increases query latency. Range: top_k - 100000. This
+                           parameter is only supported for dedicated (DRN) dense indexes. [optional]
             **kwargs: Additional keyword arguments for the API call.
 
         Returns:
@@ -1171,6 +1197,8 @@ def query_namespaces(
                 include_values=include_values,
                 include_metadata=include_metadata,
                 sparse_vector=sparse_vector,
+                scan_factor=scan_factor,
+                max_candidates=max_candidates,
                 async_threadpool_executor=True,
                 _preload_content=False,
                 **kwargs,

pinecone/db_data/index_asyncio.py

@@ -728,6 +728,8 @@ async def query(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: (SparseValues | SparseVectorTypedDict) | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> QueryResponse:
         """
@@ -832,6 +834,14 @@ async def main():
             sparse_vector: (Union[SparseValues, dict[str, Union[list[float], list[int]]]]): sparse values of the query vector.
                             Expected to be either a SparseValues object or a dict of the form:
                              {'indices': list[int], 'values': list[float]}, where the lists each have the same length.
+            scan_factor: An optimization parameter for the IVF dense indexes in dedicated
+                        read node indexes. It adjusts how much of the index is scanned to find
+                        vector candidates. Range: 0.5 - 4 (default). This parameter is only
+                        supported for dedicated (DRN) dense indexes. [optional]
+            max_candidates: An optimization parameter that controls the maximum number of
+                           candidate dense vectors to rerank. Reranking computes exact distances to
+                           improve recall but increases query latency. Range: top_k - 100000. This
+                           parameter is only supported for dedicated (DRN) dense indexes. [optional]
 
         Returns: QueryResponse object which contains the list of the closest vectors as ScoredVector objects,
                  and namespace name.
@@ -846,6 +856,8 @@ async def main():
             include_values=include_values,
             include_metadata=include_metadata,
             sparse_vector=sparse_vector,
+            scan_factor=scan_factor,
+            max_candidates=max_candidates,
             **kwargs,
         )
         return parse_query_response(response)
@@ -861,6 +873,8 @@ async def _query(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: (SparseValues | SparseVectorTypedDict) | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> OpenAPIQueryResponse:
         if len(args) > 0:
@@ -877,6 +891,8 @@ async def _query(
             include_values=include_values,
             include_metadata=include_metadata,
             sparse_vector=sparse_vector,
+            scan_factor=scan_factor,
+            max_candidates=max_candidates,
             **kwargs,
         )
         from typing import cast
@@ -897,6 +913,8 @@ async def query_namespaces(
         include_metadata: bool | None = None,
         vector: list[float] | None = None,
         sparse_vector: (SparseValues | SparseVectorTypedDict) | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> QueryNamespacesResults:
         """The query_namespaces() method is used to make a query to multiple namespaces in parallel and combine the results into one result set.
@@ -909,6 +927,14 @@ async def query_namespaces(
             include_values (Optional[bool], optional): Boolean field indicating whether vector values should be included with results. Defaults to None.
             include_metadata (Optional[bool], optional): Boolean field indicating whether vector metadata should be included with results. Defaults to None.
             sparse_vector (Optional[ Union[SparseValues, dict[str, Union[list[float], list[int]]]] ], optional): If you are working with a dotproduct index, you can pass a sparse vector as part of your hybrid search. Defaults to None.
+            scan_factor: An optimization parameter for the IVF dense indexes in dedicated
+                        read node indexes. It adjusts how much of the index is scanned to find
+                        vector candidates. Range: 0.5 - 4 (default). This parameter is only
+                        supported for dedicated (DRN) dense indexes. [optional]
+            max_candidates: An optimization parameter that controls the maximum number of
+                           candidate dense vectors to rerank. Reranking computes exact distances to
+                           improve recall but increases query latency. Range: top_k - 100000. This
+                           parameter is only supported for dedicated (DRN) dense indexes. [optional]
 
         Returns:
             QueryNamespacesResults: A QueryNamespacesResults object containing the combined results from all namespaces, as well as the combined usage cost in read units.
@@ -965,6 +991,8 @@ async def main():
                 sparse_vector=sparse_vector,
                 async_threadpool_executor=True,
                 _preload_content=False,
+                scan_factor=scan_factor,
+                max_candidates=max_candidates,
                 **kwargs,
             )
             for ns in target_namespaces

pinecone/db_data/request_factory.py

@@ -56,6 +56,8 @@ def query_request(
         include_values: bool | None = None,
         include_metadata: bool | None = None,
         sparse_vector: SparseValues | SparseVectorTypedDict | None = None,
+        scan_factor: float | None = None,
+        max_candidates: int | None = None,
         **kwargs,
     ) -> QueryRequest:
         if vector is not None and id is not None:
@@ -73,6 +75,8 @@ def query_request(
                 ("include_values", include_values),
                 ("include_metadata", include_metadata),
                 ("sparse_vector", sparse_vector_normalized),
+                ("scan_factor", scan_factor),
+                ("max_candidates", max_candidates),
             ]
         )