Implement scan_factor and max_candidates for query (#617)

## Problem
There are new parameters available on `query` for indexes with dedicated
read nodes:
- `scan_factor`
- `max_candidates`

These were pulled into the `2025-10` API release and need to be added to
the clients.

## Solution
- Regenerate core from OpenAPI and protos off of `2025-10` to pull in
`scan_factor` and `max_candidates`.
- Add `max_candidates` and `scan_factor` to the following resources and
thread things through the API:
- `VectorResourceAsyncio.query()` &&
`VectorResourceAsyncio.query_namespaces()`
  - `VectorResource.query()` && `VectorResource.query_namepspaces()` 
  - `Index.query()` && `Index.query_namespaces()`
  - `_IndexAsyncio.query()` && `_IndexAsyncio.query_namespaces()`
  - `IndexRequestFactory.query_request()`
  - `GRPCIndex.query()` && `GRPCIndex.query_namespaces()

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [X] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to not work as expected)
- [ ] This change requires a documentation update
- [ ] Infrastructure change (CI configs, etc)
- [ ] Non-code change (docs, etc)
- [ ] None of the above: (explain here)

## Test Plan
CI - unit and integration tests


<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches core query request construction and propagates new parameters
through both REST and gRPC layers; risk is mainly incorrect
serialization/forwarding or validation edge cases, mitigated by added
unit coverage.
> 
> **Overview**
> Adds two new query tuning parameters, `scan_factor` and
`max_candidates`, to the `QueryRequest` schema and surfaces them through
all query entrypoints (`Index.query`, `query_namespaces`, sync/async
vector resources, and `GRPCIndex.query`).
> 
> Regenerates the 2025-10 OpenAPI and protobuf bindings to include the
new fields (with validations and typing) and updates the request factory
to include them only when provided. Unit tests are expanded to assert
correct forwarding/omission behavior for REST, asyncio, and gRPC query
calls, and the generated API repo SHA is bumped.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0c40a43. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: austin-denoble

codegen/apis

@@ -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/grpc/protos/db_data_2025_10_pb2.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/core/grpc/protos/db_data_2025_10_pb2.pyi

@@ -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/core/openapi/db_data/model/query_request.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/index.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),
             ]
         )