pinecone.index

  1from tqdm.autonotebook import tqdm
  2from importlib.util import find_spec
  3import numbers
  4import numpy as np
  5
  6from collections.abc import Iterable, Mapping
  7from typing import Union, List, Tuple, Optional, Dict, Any
  8
  9from .core.client.model.sparse_values import SparseValues
 10from pinecone import Config
 11from pinecone.core.client import ApiClient
 12from .core.client.models import (
 13    FetchResponse,
 14    ProtobufAny,
 15    QueryRequest,
 16    QueryResponse,
 17    QueryVector,
 18    RpcStatus,
 19    ScoredVector,
 20    SingleQueryResults,
 21    DescribeIndexStatsResponse,
 22    UpsertRequest,
 23    UpsertResponse,
 24    UpdateRequest,
 25    Vector,
 26    DeleteRequest,
 27    UpdateRequest,
 28    DescribeIndexStatsRequest,
 29)
 30from pinecone.core.client.api.vector_operations_api import VectorOperationsApi
 31from pinecone.core.utils import fix_tuple_length, get_user_agent, warn_deprecated
 32import copy
 33
 34__all__ = [
 35    "Index",
 36    "FetchResponse",
 37    "ProtobufAny",
 38    "QueryRequest",
 39    "QueryResponse",
 40    "QueryVector",
 41    "RpcStatus",
 42    "ScoredVector",
 43    "SingleQueryResults",
 44    "DescribeIndexStatsResponse",
 45    "UpsertRequest",
 46    "UpsertResponse",
 47    "UpdateRequest",
 48    "Vector",
 49    "DeleteRequest",
 50    "UpdateRequest",
 51    "DescribeIndexStatsRequest",
 52    "SparseValues",
 53]
 54
 55from .core.utils.constants import REQUIRED_VECTOR_FIELDS, OPTIONAL_VECTOR_FIELDS
 56from .core.utils.error_handling import validate_and_convert_errors
 57
 58_OPENAPI_ENDPOINT_PARAMS = (
 59    "_return_http_data_only",
 60    "_preload_content",
 61    "_request_timeout",
 62    "_check_input_type",
 63    "_check_return_type",
 64    "_host_index",
 65    "async_req",
 66)
 67
 68
 69def parse_query_response(response: QueryResponse, unary_query: bool):
 70    if unary_query:
 71        response._data_store.pop("results", None)
 72    else:
 73        response._data_store.pop("matches", None)
 74        response._data_store.pop("namespace", None)
 75    return response
 76
 77
 78def upsert_numpy_deprecation_notice(context):
 79    numpy_deprecataion_notice = "The ability to pass a numpy ndarray as part of a dictionary argument to upsert() will be removed in a future version of the pinecone client. To remove this warning, use the numpy.ndarray.tolist method to convert your ndarray into a python list before calling upsert()."
 80    message = " ".join([context, numpy_deprecataion_notice])
 81    warn_deprecated(message, deprecated_in="2.2.1", removal_in="3.0.0")
 82
 83
 84class Index(ApiClient):
 85
 86    """
 87    A client for interacting with a Pinecone index via REST API.
 88    For improved performance, use the Pinecone GRPC index client.
 89    """
 90
 91    def __init__(self, index_name: str, pool_threads=1):
 92        openapi_client_config = copy.deepcopy(Config.OPENAPI_CONFIG)
 93        openapi_client_config.api_key = openapi_client_config.api_key or {}
 94        openapi_client_config.api_key["ApiKeyAuth"] = openapi_client_config.api_key.get("ApiKeyAuth", Config.API_KEY)
 95        openapi_client_config.server_variables = openapi_client_config.server_variables or {}
 96        openapi_client_config.server_variables = {
 97            **{"environment": Config.ENVIRONMENT, "index_name": index_name, "project_name": Config.PROJECT_NAME},
 98            **openapi_client_config.server_variables,
 99        }
100        super().__init__(configuration=openapi_client_config, pool_threads=pool_threads)
101        self.user_agent = get_user_agent()
102        self._vector_api = VectorOperationsApi(self)
103
104    @validate_and_convert_errors
105    def upsert(
106        self,
107        vectors: Union[List[Vector], List[tuple], List[dict]],
108        namespace: Optional[str] = None,
109        batch_size: Optional[int] = None,
110        show_progress: bool = True,
111        **kwargs,
112    ) -> UpsertResponse:
113        """
114        The upsert operation writes vectors into a namespace.
115        If a new value is upserted for an existing vector id, it will overwrite the previous value.
116
117        To upsert in parallel follow: https://docs.pinecone.io/docs/insert-data#sending-upserts-in-parallel
118
119        A vector can be represented by a 1) Vector object, a 2) tuple or 3) a dictionary
120
121        If a tuple is used, it must be of the form `(id, values, metadata)` or `(id, values)`.
122        where id is a string, vector is a list of floats, metadata is a dict,
123        and sparse_values is a dict of the form `{'indices': List[int], 'values': List[float]}`.
124
125        Examples:
126            >>> ('id1', [1.0, 2.0, 3.0], {'key': 'value'}, {'indices': [1, 2], 'values': [0.2, 0.4]})
127            >>> ('id1', [1.0, 2.0, 3.0], None, {'indices': [1, 2], 'values': [0.2, 0.4]})
128            >>> ('id1', [1.0, 2.0, 3.0], {'key': 'value'}), ('id2', [1.0, 2.0, 3.0])
129
130        If a Vector object is used, a Vector object must be of the form
131        `Vector(id, values, metadata, sparse_values)`, where metadata and sparse_values are optional
132        arguments.
133
134        Examples:
135            >>> Vector(id='id1', values=[1.0, 2.0, 3.0], metadata={'key': 'value'})
136            >>> Vector(id='id2', values=[1.0, 2.0, 3.0])
137            >>> Vector(id='id3', values=[1.0, 2.0, 3.0], sparse_values=SparseValues(indices=[1, 2], values=[0.2, 0.4]))
138
139        **Note:** the dimension of each vector must match the dimension of the index.
140
141        If a dictionary is used, it must be in the form `{'id': str, 'values': List[float], 'sparse_values': {'indices': List[int], 'values': List[float]}, 'metadata': dict}`
142
143        Examples:
144            >>> index.upsert([('id1', [1.0, 2.0, 3.0], {'key': 'value'}), ('id2', [1.0, 2.0, 3.0])])
145            >>>
146            >>> index.upsert([{'id': 'id1', 'values': [1.0, 2.0, 3.0], 'metadata': {'key': 'value'}},
147            >>>               {'id': 'id2', 'values': [1.0, 2.0, 3.0], 'sparse_values': {'indices': [1, 8], 'values': [0.2, 0.4]}])
148            >>> index.upsert([Vector(id='id1', values=[1.0, 2.0, 3.0], metadata={'key': 'value'}),
149            >>>               Vector(id='id2', values=[1.0, 2.0, 3.0], sparse_values=SparseValues(indices=[1, 2], values=[0.2, 0.4]))])
150
151        API reference: https://docs.pinecone.io/reference/upsert
152
153        Args:
154            vectors (Union[List[Vector], List[Tuple]]): A list of vectors to upsert.
155            namespace (str): The namespace to write to. If not specified, the default namespace is used. [optional]
156            batch_size (int): The number of vectors to upsert in each batch.
157                               If not specified, all vectors will be upserted in a single batch. [optional]
158            show_progress (bool): Whether to show a progress bar using tqdm.
159                                  Applied only if batch_size is provided. Default is True.
160        Keyword Args:
161            Supports OpenAPI client keyword arguments. See pinecone.core.client.models.UpsertRequest for more details.
162
163        Returns: UpsertResponse, includes the number of vectors upserted.
164        """
165        _check_type = kwargs.pop("_check_type", False)
166
167        if kwargs.get("async_req", False) and batch_size is not None:
168            raise ValueError(
169                "async_req is not supported when batch_size is provided."
170                "To upsert in parallel, please follow: "
171                "https://docs.pinecone.io/docs/insert-data#sending-upserts-in-parallel"
172            )
173
174        if batch_size is None:
175            return self._upsert_batch(vectors, namespace, _check_type, **kwargs)
176
177        if not isinstance(batch_size, int) or batch_size <= 0:
178            raise ValueError("batch_size must be a positive integer")
179
180        pbar = tqdm(total=len(vectors), disable=not show_progress, desc="Upserted vectors")
181        total_upserted = 0
182        for i in range(0, len(vectors), batch_size):
183            batch_result = self._upsert_batch(vectors[i : i + batch_size], namespace, _check_type, **kwargs)
184            pbar.update(batch_result.upserted_count)
185            # we can't use here pbar.n for the case show_progress=False
186            total_upserted += batch_result.upserted_count
187
188        return UpsertResponse(upserted_count=total_upserted)
189
190    def _upsert_batch(
191        self, vectors: List[Vector], namespace: Optional[str], _check_type: bool, **kwargs
192    ) -> UpsertResponse:
193        args_dict = self._parse_non_empty_args([("namespace", namespace)])
194
195        def _dict_to_vector(item):
196            item_keys = set(item.keys())
197            if not item_keys.issuperset(REQUIRED_VECTOR_FIELDS):
198                raise ValueError(
199                    f"Vector dictionary is missing required fields: {list(REQUIRED_VECTOR_FIELDS - item_keys)}"
200                )
201
202            excessive_keys = item_keys - (REQUIRED_VECTOR_FIELDS | OPTIONAL_VECTOR_FIELDS)
203            if len(excessive_keys) > 0:
204                raise ValueError(
205                    f"Found excess keys in the vector dictionary: {list(excessive_keys)}. "
206                    f"The allowed keys are: {list(REQUIRED_VECTOR_FIELDS | OPTIONAL_VECTOR_FIELDS)}"
207                )
208
209            if "sparse_values" in item:
210                if not isinstance(item["sparse_values"], Mapping):
211                    raise ValueError(
212                        f"Column `sparse_values` is expected to be a dictionary, found {type(item['sparse_values'])}"
213                    )
214
215                indices = item["sparse_values"].get("indices", None)
216                values = item["sparse_values"].get("values", None)
217
218                if isinstance(values, np.ndarray):
219                    upsert_numpy_deprecation_notice("Deprecated type passed in sparse_values['values'].")
220                    values = values.tolist()
221                if isinstance(indices, np.ndarray):
222                    upsert_numpy_deprecation_notice("Deprecated type passed in sparse_values['indices'].")
223                    indices = indices.tolist()
224                try:
225                    item["sparse_values"] = SparseValues(indices=indices, values=values)
226                except TypeError as e:
227                    raise ValueError(
228                        "Found unexpected data in column `sparse_values`. "
229                        "Expected format is `'sparse_values': {'indices': List[int], 'values': List[float]}`."
230                    ) from e
231
232            if "metadata" in item:
233                metadata = item.get("metadata")
234                if not isinstance(metadata, Mapping):
235                    raise TypeError(f"Column `metadata` is expected to be a dictionary, found {type(metadata)}")
236
237            if isinstance(item["values"], np.ndarray):
238                upsert_numpy_deprecation_notice("Deprecated type passed in 'values'.")
239                item["values"] = item["values"].tolist()
240
241            try:
242                return Vector(**item)
243            except TypeError as e:
244                # if not isinstance(item['values'], Iterable) or not isinstance(item['values'][0], numbers.Real):
245                #     raise TypeError(f"Column `values` is expected to be a list of floats")
246                if not isinstance(item["values"], Iterable) or not isinstance(item["values"][0], numbers.Real):
247                    raise TypeError(f"Column `values` is expected to be a list of floats")
248                raise
249
250        def _vector_transform(item: Union[Vector, Tuple]):
251            if isinstance(item, Vector):
252                return item
253            elif isinstance(item, tuple):
254                if len(item) > 3:
255                    raise ValueError(
256                        f"Found a tuple of length {len(item)} which is not supported. "
257                        f"Vectors can be represented as tuples either the form (id, values, metadata) or (id, values). "
258                        f"To pass sparse values please use either dicts or a Vector objects as inputs."
259                    )
260                id, values, metadata = fix_tuple_length(item, 3)
261                return Vector(id=id, values=values, metadata=metadata or {}, _check_type=_check_type)
262            elif isinstance(item, Mapping):
263                return _dict_to_vector(item)
264            raise ValueError(f"Invalid vector value passed: cannot interpret type {type(item)}")
265
266        return self._vector_api.upsert(
267            UpsertRequest(
268                vectors=list(map(_vector_transform, vectors)),
269                **args_dict,
270                _check_type=_check_type,
271                **{k: v for k, v in kwargs.items() if k not in _OPENAPI_ENDPOINT_PARAMS},
272            ),
273            **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
274        )
275
276    @staticmethod
277    def _iter_dataframe(df, batch_size):
278        for i in range(0, len(df), batch_size):
279            batch = df.iloc[i : i + batch_size].to_dict(orient="records")
280            yield batch
281
282    def upsert_from_dataframe(
283        self, df, namespace: str = None, batch_size: int = 500, show_progress: bool = True
284    ) -> UpsertResponse:
285        """Upserts a dataframe into the index.
286
287        Args:
288            df: A pandas dataframe with the following columns: id, vector, sparse_values, and metadata.
289            namespace: The namespace to upsert into.
290            batch_size: The number of rows to upsert in a single batch.
291            show_progress: Whether to show a progress bar.
292        """
293        try:
294            import pandas as pd
295        except ImportError:
296            raise RuntimeError(
297                "The `pandas` package is not installed. Please install pandas to use `upsert_from_dataframe()`"
298            )
299
300        if not isinstance(df, pd.DataFrame):
301            raise ValueError(f"Only pandas dataframes are supported. Found: {type(df)}")
302
303        pbar = tqdm(total=len(df), disable=not show_progress, desc="sending upsert requests")
304        results = []
305        for chunk in self._iter_dataframe(df, batch_size=batch_size):
306            res = self.upsert(vectors=chunk, namespace=namespace)
307            pbar.update(len(chunk))
308            results.append(res)
309
310        upserted_count = 0
311        for res in results:
312            upserted_count += res.upserted_count
313
314        return UpsertResponse(upserted_count=upserted_count)
315
316    @validate_and_convert_errors
317    def delete(
318        self,
319        ids: Optional[List[str]] = None,
320        delete_all: Optional[bool] = None,
321        namespace: Optional[str] = None,
322        filter: Optional[Dict[str, Union[str, float, int, bool, List, dict]]] = None,
323        **kwargs,
324    ) -> Dict[str, Any]:
325        """
326        The Delete operation deletes vectors from the index, from a single namespace.
327        No error raised if the vector id does not exist.
328        Note: for any delete call, if namespace is not specified, the default namespace is used.
329
330        Delete can occur in the following mutual exclusive ways:
331        1. Delete by ids from a single namespace
332        2. Delete all vectors from a single namespace by setting delete_all to True
333        3. Delete all vectors from a single namespace by specifying a metadata filter
334            (note that for this option delete all must be set to False)
335
336        API reference: https://docs.pinecone.io/reference/delete_post
337
338        Examples:
339            >>> index.delete(ids=['id1', 'id2'], namespace='my_namespace')
340            >>> index.delete(delete_all=True, namespace='my_namespace')
341            >>> index.delete(filter={'key': 'value'}, namespace='my_namespace')
342
343        Args:
344            ids (List[str]): Vector ids to delete [optional]
345            delete_all (bool): This indicates that all vectors in the index namespace should be deleted.. [optional]
346                                Default is False.
347            namespace (str): The namespace to delete vectors from [optional]
348                            If not specified, the default namespace is used.
349            filter (Dict[str, Union[str, float, int, bool, List, dict]]):
350                    If specified, the metadata filter here will be used to select the vectors to delete.
351                    This is mutually exclusive with specifying ids to delete in the ids param or using delete_all=True.
352                    See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
353
354        Keyword Args:
355          Supports OpenAPI client keyword arguments. See pinecone.core.client.models.DeleteRequest for more details.
356
357
358          Returns: An empty dictionary if the delete operation was successful.
359        """
360        _check_type = kwargs.pop("_check_type", False)
361        args_dict = self._parse_non_empty_args(
362            [("ids", ids), ("delete_all", delete_all), ("namespace", namespace), ("filter", filter)]
363        )
364
365        return self._vector_api.delete(
366            DeleteRequest(
367                **args_dict,
368                **{k: v for k, v in kwargs.items() if k not in _OPENAPI_ENDPOINT_PARAMS and v is not None},
369                _check_type=_check_type,
370            ),
371            **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
372        )
373
374    @validate_and_convert_errors
375    def fetch(self, ids: List[str], namespace: Optional[str] = None, **kwargs) -> FetchResponse:
376        """
377        The fetch operation looks up and returns vectors, by ID, from a single namespace.
378        The returned vectors include the vector data and/or metadata.
379
380        API reference: https://docs.pinecone.io/reference/fetch
381
382        Examples:
383            >>> index.fetch(ids=['id1', 'id2'], namespace='my_namespace')
384            >>> index.fetch(ids=['id1', 'id2'])
385
386        Args:
387            ids (List[str]): The vector IDs to fetch.
388            namespace (str): The namespace to fetch vectors from.
389                             If not specified, the default namespace is used. [optional]
390        Keyword Args:
391            Supports OpenAPI client keyword arguments. See pinecone.core.client.models.FetchResponse for more details.
392
393
394        Returns: FetchResponse object which contains the list of Vector objects, and namespace name.
395        """
396        args_dict = self._parse_non_empty_args([("namespace", namespace)])
397        return self._vector_api.fetch(ids=ids, **args_dict, **kwargs)
398
399    @validate_and_convert_errors
400    def query(
401        self,
402        vector: Optional[List[float]] = None,
403        id: Optional[str] = None,
404        queries: Optional[Union[List[QueryVector], List[Tuple]]] = None,
405        top_k: Optional[int] = None,
406        namespace: Optional[str] = None,
407        filter: Optional[Dict[str, Union[str, float, int, bool, List, dict]]] = None,
408        include_values: Optional[bool] = None,
409        include_metadata: Optional[bool] = None,
410        sparse_vector: Optional[Union[SparseValues, Dict[str, Union[List[float], List[int]]]]] = None,
411        **kwargs,
412    ) -> QueryResponse:
413        """
414        The Query operation searches a namespace, using a query vector.
415        It retrieves the ids of the most similar items in a namespace, along with their similarity scores.
416
417        API reference: https://docs.pinecone.io/reference/query
418
419        Examples:
420            >>> index.query(vector=[1, 2, 3], top_k=10, namespace='my_namespace')
421            >>> index.query(id='id1', top_k=10, namespace='my_namespace')
422            >>> index.query(vector=[1, 2, 3], top_k=10, namespace='my_namespace', filter={'key': 'value'})
423            >>> index.query(id='id1', top_k=10, namespace='my_namespace', include_metadata=True, include_values=True)
424            >>> index.query(vector=[1, 2, 3], sparse_vector={'indices': [1, 2], 'values': [0.2, 0.4]},
425            >>>             top_k=10, namespace='my_namespace')
426            >>> index.query(vector=[1, 2, 3], sparse_vector=SparseValues([1, 2], [0.2, 0.4]),
427            >>>             top_k=10, namespace='my_namespace')
428
429        Args:
430            vector (List[float]): The query vector. This should be the same length as the dimension of the index
431                                  being queried. Each `query()` request can contain only one of the parameters
432                                  `queries`, `id` or `vector`.. [optional]
433            id (str): The unique ID of the vector to be used as a query vector.
434                      Each `query()` request can contain only one of the parameters
435                      `queries`, `vector`, or  `id`.. [optional]
436            queries ([QueryVector]): DEPRECATED. The query vectors.
437                                     Each `query()` request can contain only one of the parameters
438                                     `queries`, `vector`, or  `id`.. [optional]
439            top_k (int): The number of results to return for each query. Must be an integer greater than 1.
440            namespace (str): The namespace to fetch vectors from.
441                             If not specified, the default namespace is used. [optional]
442            filter (Dict[str, Union[str, float, int, bool, List, dict]):
443                    The filter to apply. You can use vector metadata to limit your search.
444                    See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
445            include_values (bool): Indicates whether vector values are included in the response.
446                                   If omitted the server will use the default value of False [optional]
447            include_metadata (bool): Indicates whether metadata is included in the response as well as the ids.
448                                     If omitted the server will use the default value of False  [optional]
449            sparse_vector: (Union[SparseValues, Dict[str, Union[List[float], List[int]]]]): sparse values of the query vector.
450                            Expected to be either a SparseValues object or a dict of the form:
451                             {'indices': List[int], 'values': List[float]}, where the lists each have the same length.
452        Keyword Args:
453            Supports OpenAPI client keyword arguments. See pinecone.core.client.models.QueryRequest for more details.
454
455        Returns: QueryResponse object which contains the list of the closest vectors as ScoredVector objects,
456                 and namespace name.
457        """
458
459        def _query_transform(item):
460            if isinstance(item, QueryVector):
461                return item
462            if isinstance(item, tuple):
463                values, filter = fix_tuple_length(item, 2)
464                if filter is None:
465                    return QueryVector(values=values, _check_type=_check_type)
466                else:
467                    return QueryVector(values=values, filter=filter, _check_type=_check_type)
468            if isinstance(item, Iterable):
469                return QueryVector(values=item, _check_type=_check_type)
470            raise ValueError(f"Invalid query vector value passed: cannot interpret type {type(item)}")
471
472        _check_type = kwargs.pop("_check_type", False)
473        queries = list(map(_query_transform, queries)) if queries is not None else None
474
475        sparse_vector = self._parse_sparse_values_arg(sparse_vector)
476        args_dict = self._parse_non_empty_args(
477            [
478                ("vector", vector),
479                ("id", id),
480                ("queries", queries),
481                ("top_k", top_k),
482                ("namespace", namespace),
483                ("filter", filter),
484                ("include_values", include_values),
485                ("include_metadata", include_metadata),
486                ("sparse_vector", sparse_vector),
487            ]
488        )
489        response = self._vector_api.query(
490            QueryRequest(
491                **args_dict,
492                _check_type=_check_type,
493                **{k: v for k, v in kwargs.items() if k not in _OPENAPI_ENDPOINT_PARAMS},
494            ),
495            **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
496        )
497        return parse_query_response(response, vector is not None or id)
498
499    @validate_and_convert_errors
500    def update(
501        self,
502        id: str,
503        values: Optional[List[float]] = None,
504        set_metadata: Optional[Dict[str, Union[str, float, int, bool, List[int], List[float], List[str]]]] = None,
505        namespace: Optional[str] = None,
506        sparse_values: Optional[Union[SparseValues, Dict[str, Union[List[float], List[int]]]]] = None,
507        **kwargs,
508    ) -> Dict[str, Any]:
509        """
510        The Update operation updates vector in a namespace.
511        If a value is included, it will overwrite the previous value.
512        If a set_metadata is included,
513        the values of the fields specified in it will be added or overwrite the previous value.
514
515        API reference: https://docs.pinecone.io/reference/update
516
517        Examples:
518            >>> index.update(id='id1', values=[1, 2, 3], namespace='my_namespace')
519            >>> index.update(id='id1', set_metadata={'key': 'value'}, namespace='my_namespace')
520            >>> index.update(id='id1', values=[1, 2, 3], sparse_values={'indices': [1, 2], 'values': [0.2, 0.4]},
521            >>>              namespace='my_namespace')
522            >>> index.update(id='id1', values=[1, 2, 3], sparse_values=SparseValues(indices=[1, 2], values=[0.2, 0.4]),
523            >>>              namespace='my_namespace')
524
525        Args:
526            id (str): Vector's unique id.
527            values (List[float]): vector values to set. [optional]
528            set_metadata (Dict[str, Union[str, float, int, bool, List[int], List[float], List[str]]]]):
529                metadata to set for vector. [optional]
530            namespace (str): Namespace name where to update the vector.. [optional]
531            sparse_values: (Dict[str, Union[List[float], List[int]]]): sparse values to update for the vector.
532                           Expected to be either a SparseValues object or a dict of the form:
533                           {'indices': List[int], 'values': List[float]} where the lists each have the same length.
534
535        Keyword Args:
536            Supports OpenAPI client keyword arguments. See pinecone.core.client.models.UpdateRequest for more details.
537
538        Returns: An empty dictionary if the update was successful.
539        """
540        _check_type = kwargs.pop("_check_type", False)
541        sparse_values = self._parse_sparse_values_arg(sparse_values)
542        args_dict = self._parse_non_empty_args(
543            [
544                ("values", values),
545                ("set_metadata", set_metadata),
546                ("namespace", namespace),
547                ("sparse_values", sparse_values),
548            ]
549        )
550        return self._vector_api.update(
551            UpdateRequest(
552                id=id,
553                **args_dict,
554                _check_type=_check_type,
555                **{k: v for k, v in kwargs.items() if k not in _OPENAPI_ENDPOINT_PARAMS},
556            ),
557            **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
558        )
559
560    @validate_and_convert_errors
561    def describe_index_stats(
562        self, filter: Optional[Dict[str, Union[str, float, int, bool, List, dict]]] = None, **kwargs
563    ) -> DescribeIndexStatsResponse:
564        """
565        The DescribeIndexStats operation returns statistics about the index's contents.
566        For example: The vector count per namespace and the number of dimensions.
567
568        API reference: https://docs.pinecone.io/reference/describe_index_stats_post
569
570        Examples:
571            >>> index.describe_index_stats()
572            >>> index.describe_index_stats(filter={'key': 'value'})
573
574        Args:
575            filter (Dict[str, Union[str, float, int, bool, List, dict]]):
576            If this parameter is present, the operation only returns statistics for vectors that satisfy the filter.
577            See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
578
579        Returns: DescribeIndexStatsResponse object which contains stats about the index.
580        """
581        _check_type = kwargs.pop("_check_type", False)
582        args_dict = self._parse_non_empty_args([("filter", filter)])
583
584        return self._vector_api.describe_index_stats(
585            DescribeIndexStatsRequest(
586                **args_dict,
587                **{k: v for k, v in kwargs.items() if k not in _OPENAPI_ENDPOINT_PARAMS},
588                _check_type=_check_type,
589            ),
590            **{k: v for k, v in kwargs.items() if k in _OPENAPI_ENDPOINT_PARAMS},
591        )
592
593    @staticmethod
594    def _parse_non_empty_args(args: List[Tuple[str, Any]]) -> Dict[str, Any]:
595        return {arg_name: val for arg_name, val in args if val is not None}
596
597    @staticmethod
598    def _parse_sparse_values_arg(
599        sparse_values: Optional[Union[SparseValues, Dict[str, Union[List[float], List[int]]]]]
600    ) -> Optional[SparseValues]:
601        if sparse_values is None:
602            return None
603
604        if isinstance(sparse_values, SparseValues):
605            return sparse_values
606
607        if not isinstance(sparse_values, dict) or "indices" not in sparse_values or "values" not in sparse_values:
608            raise ValueError(
609                "Invalid sparse values argument. Expected a dict of: {'indices': List[int], 'values': List[float]}."
610                f"Received: {sparse_values}"
611            )
612
613        return SparseValues(indices=sparse_values["indices"], values=sparse_values["values"])