pinecone.data.index_asyncio_interface

  1from abc import ABC, abstractmethod
  2from typing import Union, List, Optional, Dict, Any
  3
  4from pinecone.core.openapi.db_data.models import (
  5    FetchResponse,
  6    QueryResponse,
  7    IndexDescription as DescribeIndexStatsResponse,
  8    UpsertResponse,
  9    Vector,
 10    ListResponse,
 11    SparseValues,
 12    SearchRecordsResponse,
 13)
 14from .query_results_aggregator import QueryNamespacesResults
 15from .types import (
 16    VectorTypedDict,
 17    SparseVectorTypedDict,
 18    VectorMetadataTypedDict,
 19    FilterTypedDict,
 20    VectorTuple,
 21    VectorTupleWithMetadata,
 22    SearchQueryTypedDict,
 23    SearchRerankTypedDict,
 24)
 25from .dataclasses import SearchQuery, SearchRerank
 26
 27
 28class IndexAsyncioInterface(ABC):
 29    @abstractmethod
 30    async def upsert(
 31        self,
 32        vectors: Union[
 33            List[Vector], List[VectorTuple], List[VectorTupleWithMetadata], List[VectorTypedDict]
 34        ],
 35        namespace: Optional[str] = None,
 36        batch_size: Optional[int] = None,
 37        show_progress: bool = True,
 38        **kwargs,
 39    ) -> UpsertResponse:
 40        """
 41        Args:
 42            vectors (Union[List[Vector], List[VectorTuple], List[VectorTupleWithMetadata], List[VectorTypedDict]]): A list of vectors to upsert.
 43            namespace (str): The namespace to write to. If not specified, the default namespace is used. [optional]
 44            batch_size (int): The number of vectors to upsert in each batch.
 45                               If not specified, all vectors will be upserted in a single batch. [optional]
 46            show_progress (bool): Whether to show a progress bar using tqdm.
 47                                  Applied only if batch_size is provided. Default is True.
 48
 49        Returns:
 50            `UpsertResponse`, includes the number of vectors upserted.
 51
 52
 53        The upsert operation writes vectors into a namespace.
 54        If a new value is upserted for an existing vector id, it will overwrite the previous value.
 55
 56        To upsert in parallel follow: https://docs.pinecone.io/docs/insert-data#sending-upserts-in-parallel
 57
 58        ## Upserting dense vectors
 59
 60        **Note:** the dimension of each dense vector must match the dimension of the index.
 61
 62        A vector can be represented in a variety of ways.
 63
 64        ```python
 65        import asyncio
 66        from pinecone import Pinecone, Vector
 67
 68        async def main():
 69            pc = Pinecone()
 70            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
 71                # A Vector object
 72                await idx.upsert(
 73                    namespace = 'my-namespace',
 74                    vectors = [
 75                        Vector(id='id1', values=[0.1, 0.2, 0.3, 0.4], metadata={'metadata_key': 'metadata_value'}),
 76                    ]
 77                )
 78
 79                # A vector tuple
 80                await idx.upsert(
 81                    namespace = 'my-namespace',
 82                    vectors = [
 83                        ('id1', [0.1, 0.2, 0.3, 0.4]),
 84                    ]
 85                )
 86
 87                # A vector tuple with metadata
 88                await idx.upsert(
 89                    namespace = 'my-namespace',
 90                    vectors = [
 91                        ('id1', [0.1, 0.2, 0.3, 0.4], {'metadata_key': 'metadata_value'}),
 92                    ]
 93                )
 94
 95                # A vector dictionary
 96                await idx.upsert(
 97                    namespace = 'my-namespace',
 98                    vectors = [
 99                        {"id": 1, "values": [0.1, 0.2, 0.3, 0.4], "metadata": {"metadata_key": "metadata_value"}},
100                    ]
101
102        asyncio.run(main())
103        ```
104
105        ## Upserting sparse vectors
106
107        ```python
108        import asyncio
109        from pinecone import Pinecone, Vector, SparseValues
110
111        async def main():
112            pc = Pinecone()
113            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
114                # A Vector object
115                await idx.upsert(
116                    namespace = 'my-namespace',
117                    vectors = [
118                        Vector(id='id1', sparse_values=SparseValues(indices=[1, 2], values=[0.2, 0.4])),
119                    ]
120                )
121
122                # A dictionary
123                await idx.upsert(
124                    namespace = 'my-namespace',
125                    vectors = [
126                        {"id": 1, "sparse_values": {"indices": [1, 2], "values": [0.2, 0.4]}},
127                    ]
128                )
129
130        asyncio.run(main())
131        ```
132
133        ## Batch upsert
134
135        If you have a large number of vectors, you can upsert them in batches.
136
137        ```python
138        import asyncio
139        from pinecone import Pinecone, Vector, SparseValues
140
141        async def main():
142            pc = Pinecone()
143            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
144
145            await idx.upsert(
146                namespace = 'my-namespace',
147                vectors = [
148                    {'id': 'id1', 'values': [0.1, 0.2, 0.3, 0.4]},
149                    {'id': 'id2', 'values': [0.2, 0.3, 0.4, 0.5]},
150                    {'id': 'id3', 'values': [0.3, 0.4, 0.5, 0.6]},
151                    {'id': 'id4', 'values': [0.4, 0.5, 0.6, 0.7]},
152                    {'id': 'id5', 'values': [0.5, 0.6, 0.7, 0.8]},
153                    # More vectors here
154                ],
155                batch_size = 50
156            )
157
158        asyncio.run(main())
159        ```
160
161        ## Visual progress bar with tqdm
162
163        To see a progress bar when upserting in batches, you will need to separately install the `tqdm` package.
164        If `tqdm` is present, the client will detect and use it to display progress when `show_progress=True`.
165        """
166        pass
167
168    @abstractmethod
169    async def upsert_from_dataframe(
170        self, df, namespace: Optional[str] = None, batch_size: int = 500, show_progress: bool = True
171    ):
172        """This method has not been implemented yet for the IndexAsyncio class."""
173        pass
174
175    @abstractmethod
176    async def delete(
177        self,
178        ids: Optional[List[str]] = None,
179        delete_all: Optional[bool] = None,
180        namespace: Optional[str] = None,
181        filter: Optional[FilterTypedDict] = None,
182        **kwargs,
183    ) -> Dict[str, Any]:
184        """
185        Args:
186            ids (List[str]): Vector ids to delete [optional]
187            delete_all (bool): This indicates that all vectors in the index namespace should be deleted.. [optional]
188                                Default is False.
189            namespace (str): The namespace to delete vectors from [optional]
190                            If not specified, the default namespace is used.
191            filter (Dict[str, Union[str, float, int, bool, List, dict]]):
192                    If specified, the metadata filter here will be used to select the vectors to delete.
193                    This is mutually exclusive with specifying ids to delete in the ids param or using delete_all=True.
194                    See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
195
196
197        The Delete operation deletes vectors from the index, from a single namespace.
198
199        No error is raised if the vector id does not exist.
200
201        Note: For any delete call, if namespace is not specified, the default namespace `""` is used.
202        Since the delete operation does not error when ids are not present, this means you may not receive
203        an error if you delete from the wrong namespace.
204
205        Delete can occur in the following mutual exclusive ways:
206        1. Delete by ids from a single namespace
207        2. Delete all vectors from a single namespace by setting delete_all to True
208        3. Delete all vectors from a single namespace by specifying a metadata filter
209            (note that for this option delete all must be set to False)
210
211        API reference: https://docs.pinecone.io/reference/delete_post
212
213        ```python
214        import asyncio
215        from pinecone import Pinecone, Vector, SparseValues
216
217        async def main():
218            pc = Pinecone()
219            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
220                # Delete specific ids
221                await idx.delete(
222                    ids=['id1', 'id2'],
223                    namespace='my_namespace'
224                )
225
226                # Delete everything in a namespace
227                await idx.delete(
228                    delete_all=True,
229                    namespace='my_namespace'
230                )
231
232                # Delete by metadata filter
233                await idx.delete(
234                    filter={'key': 'value'},
235                    namespace='my_namespace'
236                )
237
238        asyncio.run(main())
239        ```
240
241          Returns: An empty dictionary if the delete operation was successful.
242        """
243        pass
244
245    @abstractmethod
246    async def fetch(
247        self, ids: List[str], namespace: Optional[str] = None, **kwargs
248    ) -> FetchResponse:
249        """
250        The fetch operation looks up and returns vectors, by ID, from a single namespace.
251        The returned vectors include the vector data and/or metadata.
252
253        API reference: https://docs.pinecone.io/reference/fetch
254
255        ```
256        import asyncio
257        from pinecone import Pinecone, Vector, SparseValues
258
259        async def main():
260            pc = Pinecone()
261            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
262                # Fetch specific ids in namespace
263                fetched = await idx.fetch(
264                    ids=['id1', 'id2'],
265                    namespace='my_namespace'
266                )
267                for vec_id in fetched.vectors:
268                    vector = fetched.vectors[vec_id]
269                    print(vector.id)
270                    print(vector.metadata)
271                    print(vector.values)
272
273        asyncio.run(main())
274        ```
275
276        Args:
277            ids (List[str]): The vector IDs to fetch.
278            namespace (str): The namespace to fetch vectors from.
279                             If not specified, the default namespace is used. [optional]
280
281        Returns: FetchResponse object which contains the list of Vector objects, and namespace name.
282        """
283        pass
284
285    @abstractmethod
286    async def query(
287        self,
288        *args,
289        top_k: int,
290        vector: Optional[List[float]] = None,
291        id: Optional[str] = None,
292        namespace: Optional[str] = None,
293        filter: Optional[FilterTypedDict] = None,
294        include_values: Optional[bool] = None,
295        include_metadata: Optional[bool] = None,
296        sparse_vector: Optional[Union[SparseValues, SparseVectorTypedDict]] = None,
297        **kwargs,
298    ) -> QueryResponse:
299        """
300        The Query operation searches a namespace, using a query vector.
301        It retrieves the ids of the most similar items in a namespace, along with their similarity scores.
302
303        API reference: https://docs.pinecone.io/reference/query
304
305        ## Querying with dense vectors
306
307        ```python
308        import asyncio
309        from pinecone import Pinecone, Vector, SparseValues
310
311        async def main():
312            pc = Pinecone()
313            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
314                query_embedding = [0.1, 0.2, 0.3, ...] # An embedding that matches the index dimension
315
316                # Query by vector values
317                results = await idx.query(
318                    vector=query_embedding,
319                    top_k=10,
320                    filter={'genre': {"$eq": "drama"}}, # Optionally filter by metadata
321                    namespace='my_namespace',
322                    include_values=False,
323                    include_metadata=True
324                )
325
326                # Query using vector id (the values from this stored vector will be used to query)
327                results = await idx.query(
328                    id='1',
329                    top_k=10,
330                    filter={"year": {"$gt": 2000}},
331                    namespace='my_namespace',
332                )
333
334        asyncio.run(main())
335        ```
336
337        ## Query with sparse vectors
338
339        ```python
340        import asyncio
341        from pinecone import Pinecone, Vector, SparseValues
342
343        async def main():
344            pc = Pinecone()
345            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
346                query_embedding = [0.1, 0.2, 0.3, ...] # An embedding that matches the index dimension
347
348                # Query by vector values
349                results = await idx.query(
350                    vector=query_embedding,
351                    top_k=10,
352                    filter={'genre': {"$eq": "drama"}}, # Optionally filter by metadata
353                    namespace='my_namespace',
354                    include_values=False,
355                    include_metadata=True
356                )
357
358                # Query using vector id (the values from this stored vector will be used to query)
359                results = await idx.query(
360                    id='1',
361                    top_k=10,
362                    filter={"year": {"$gt": 2000}},
363                    namespace='my_namespace',
364                )
365
366        asyncio.run(main())
367        ```
368
369        Examples:
370            >>> index.query(vector=[1, 2, 3], top_k=10, namespace='my_namespace')
371            >>> index.query(id='id1', top_k=10, namespace='my_namespace')
372            >>> index.query(vector=[1, 2, 3], top_k=10, namespace='my_namespace', filter={'key': 'value'})
373            >>> index.query(id='id1', top_k=10, namespace='my_namespace', include_metadata=True, include_values=True)
374            >>> index.query(vector=[1, 2, 3], sparse_vector={'indices': [1, 2], 'values': [0.2, 0.4]},
375            >>>             top_k=10, namespace='my_namespace')
376            >>> index.query(vector=[1, 2, 3], sparse_vector=SparseValues([1, 2], [0.2, 0.4]),
377            >>>             top_k=10, namespace='my_namespace')
378
379        Args:
380            vector (List[float]): The query vector. This should be the same length as the dimension of the index
381                                  being queried. Each `query()` request can contain only one of the parameters
382                                  `id` or `vector`.. [optional]
383            id (str): The unique ID of the vector to be used as a query vector.
384                      Each `query()` request can contain only one of the parameters
385                      `vector` or  `id`. [optional]
386            top_k (int): The number of results to return for each query. Must be an integer greater than 1.
387            namespace (str): The namespace to fetch vectors from.
388                             If not specified, the default namespace is used. [optional]
389            filter (Dict[str, Union[str, float, int, bool, List, dict]):
390                    The filter to apply. You can use vector metadata to limit your search.
391                    See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
392            include_values (bool): Indicates whether vector values are included in the response.
393                                   If omitted the server will use the default value of False [optional]
394            include_metadata (bool): Indicates whether metadata is included in the response as well as the ids.
395                                     If omitted the server will use the default value of False  [optional]
396            sparse_vector: (Union[SparseValues, Dict[str, Union[List[float], List[int]]]]): sparse values of the query vector.
397                            Expected to be either a SparseValues object or a dict of the form:
398                             {'indices': List[int], 'values': List[float]}, where the lists each have the same length.
399
400        Returns: QueryResponse object which contains the list of the closest vectors as ScoredVector objects,
401                 and namespace name.
402        """
403        pass
404
405    @abstractmethod
406    async def query_namespaces(
407        self,
408        namespaces: List[str],
409        top_k: Optional[int] = None,
410        filter: Optional[FilterTypedDict] = None,
411        include_values: Optional[bool] = None,
412        include_metadata: Optional[bool] = None,
413        vector: Optional[List[float]] = None,
414        sparse_vector: Optional[Union[SparseValues, SparseVectorTypedDict]] = None,
415        **kwargs,
416    ) -> QueryNamespacesResults:
417        """The query_namespaces() method is used to make a query to multiple namespaces in parallel and combine the results into one result set.
418
419        Args:
420            vector (List[float]): The query vector, must be the same length as the dimension of the index being queried.
421            namespaces (List[str]): The list of namespaces to query.
422            top_k (Optional[int], optional): The number of results you would like to request from each namespace. Defaults to 10.
423            filter (Optional[Dict[str, Union[str, float, int, bool, List, dict]]], optional): Pass an optional filter to filter results based on metadata. Defaults to None.
424            include_values (Optional[bool], optional): Boolean field indicating whether vector values should be included with results. Defaults to None.
425            include_metadata (Optional[bool], optional): Boolean field indicating whether vector metadata should be included with results. Defaults to None.
426            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.
427
428        Returns:
429            QueryNamespacesResults: A QueryNamespacesResults object containing the combined results from all namespaces, as well as the combined usage cost in read units.
430
431        Examples:
432
433        ```python
434        import asyncio
435        from pinecone import Pinecone
436
437        async def main():
438            pc = Pinecone(api_key="your-api-key")
439            idx = pc.IndexAsyncio(
440                host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io",
441            )
442
443            query_vec = [0.1, 0.2, 0.3] # An embedding that matches the index dimension
444            combined_results = await idx.query_namespaces(
445                vector=query_vec,
446                namespaces=['ns1', 'ns2', 'ns3', 'ns4'],
447                top_k=10,
448                filter={'genre': {"$eq": "drama"}},
449                include_values=True,
450                include_metadata=True
451            )
452            for vec in combined_results.matches:
453                print(vec.id, vec.score)
454            print(combined_results.usage)
455
456            await idx.close()
457
458        asyncio.run(main())
459        ```
460        """
461        pass
462
463    @abstractmethod
464    async def update(
465        self,
466        id: str,
467        values: Optional[List[float]] = None,
468        set_metadata: Optional[VectorMetadataTypedDict] = None,
469        namespace: Optional[str] = None,
470        sparse_values: Optional[Union[SparseValues, SparseVectorTypedDict]] = None,
471        **kwargs,
472    ) -> Dict[str, Any]:
473        """
474        The Update operation updates vector in a namespace.
475
476        Args:
477            id (str): Vector's unique id.
478            values (List[float]): vector values to set. [optional]
479            set_metadata (Dict[str, Union[str, float, int, bool, List[int], List[float], List[str]]]]):
480                metadata to set for vector. [optional]
481            namespace (str): Namespace name where to update the vector.. [optional]
482            sparse_values: (Dict[str, Union[List[float], List[int]]]): sparse values to update for the vector.
483                           Expected to be either a SparseValues object or a dict of the form:
484                           {'indices': List[int], 'values': List[float]} where the lists each have the same length.
485
486        If a value is included, it will overwrite the previous value.
487        If a set_metadata is included,
488        the values of the fields specified in it will be added or overwrite the previous value.
489
490        API reference: https://docs.pinecone.io/reference/update
491
492        Examples:
493        ```python
494        import asyncio
495        from pinecone import Pinecone, Vector, SparseValues
496
497        async def main():
498            pc = Pinecone()
499            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
500                # Update vector values
501                await idx.update(
502                    id='id1',
503                    values=[0.1, 0.2, 0.3, ...],
504                    namespace='my_namespace'
505                )
506
507                # Update metadata
508                await idx.update(
509                    id='id1',
510                    set_metadata={'key': 'value'},
511                    namespace='my_namespace'
512                )
513
514                # Update sparse values
515                await idx.update(
516                    id='id1',
517                    sparse_values={'indices': [1, 2], 'values': [0.2, 0.4]},
518                    namespace='my_namespace'
519                )
520
521                # Update sparse values with SparseValues object
522                await idx.update(
523                    id='id1',
524                    sparse_values=SparseValues(indices=[234781, 5432], values=[0.2, 0.4]),
525                    namespace='my_namespace'
526                )
527
528        asyncio.run(main())
529        ```
530
531        """
532        pass
533
534    @abstractmethod
535    async def describe_index_stats(
536        self, filter: Optional[FilterTypedDict] = None, **kwargs
537    ) -> DescribeIndexStatsResponse:
538        """
539        The DescribeIndexStats operation returns statistics about the index's contents.
540        For example: The vector count per namespace and the number of dimensions.
541
542        API reference: https://docs.pinecone.io/reference/describe_index_stats_post
543
544        Args:
545            filter (Dict[str, Union[str, float, int, bool, List, dict]]):
546            If this parameter is present, the operation only returns statistics for vectors that satisfy the filter.
547            See https://www.pinecone.io/docs/metadata-filtering/.. [optional]
548
549        Returns: DescribeIndexStatsResponse object which contains stats about the index.
550
551        ```python
552        import asyncio
553        from pinecone import Pinecone, Vector, SparseValues
554
555        async def main():
556            pc = Pinecone()
557            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
558                print(await idx.describe_index_stats())
559
560        asyncio.run(main())
561        ```
562        """
563        pass
564
565    @abstractmethod
566    async def list_paginated(
567        self,
568        prefix: Optional[str] = None,
569        limit: Optional[int] = None,
570        pagination_token: Optional[str] = None,
571        namespace: Optional[str] = None,
572        **kwargs,
573    ) -> ListResponse:
574        """
575        The list_paginated operation finds vectors based on an id prefix within a single namespace.
576        It returns matching ids in a paginated form, with a pagination token to fetch the next page of results.
577        This id list can then be passed to fetch or delete operations, depending on your use case.
578
579        Consider using the `list` method to avoid having to handle pagination tokens manually.
580
581        Examples:
582            >>> results = index.list_paginated(prefix='99', limit=5, namespace='my_namespace')
583            >>> [v.id for v in results.vectors]
584            ['99', '990', '991', '992', '993']
585            >>> results.pagination.next
586            eyJza2lwX3Bhc3QiOiI5OTMiLCJwcmVmaXgiOiI5OSJ9
587            >>> next_results = index.list_paginated(prefix='99', limit=5, namespace='my_namespace', pagination_token=results.pagination.next)
588
589        Args:
590            prefix (Optional[str]): The id prefix to match. If unspecified, an empty string prefix will
591                                    be used with the effect of listing all ids in a namespace [optional]
592            limit (Optional[int]): The maximum number of ids to return. If unspecified, the server will use a default value. [optional]
593            pagination_token (Optional[str]): A token needed to fetch the next page of results. This token is returned
594                in the response if additional results are available. [optional]
595            namespace (Optional[str]): The namespace to fetch vectors from. If not specified, the default namespace is used. [optional]
596
597        Returns: ListResponse object which contains the list of ids, the namespace name, pagination information, and usage showing the number of read_units consumed.
598        """
599        pass
600
601    @abstractmethod
602    async def list(self, **kwargs):
603        """
604        The list operation accepts all of the same arguments as list_paginated, and returns a generator that yields
605        a list of the matching vector ids in each page of results. It automatically handles pagination tokens on your
606        behalf.
607
608        Examples:
609            >>> for ids in index.list(prefix='99', limit=5, namespace='my_namespace'):
610            >>>     print(ids)
611            ['99', '990', '991', '992', '993']
612            ['994', '995', '996', '997', '998']
613            ['999']
614
615        Args:
616            prefix (Optional[str]): The id prefix to match. If unspecified, an empty string prefix will
617                                    be used with the effect of listing all ids in a namespace [optional]
618            limit (Optional[int]): The maximum number of ids to return. If unspecified, the server will use a default value. [optional]
619            pagination_token (Optional[str]): A token needed to fetch the next page of results. This token is returned
620                in the response if additional results are available. [optional]
621            namespace (Optional[str]): The namespace to fetch vectors from. If not specified, the default namespace is used. [optional]
622        """
623        pass
624
625    @abstractmethod
626    async def upsert_records(self, namespace: str, records: List[Dict]):
627        """
628        :param namespace: The namespace of the index to upsert records to.
629        :type namespace: str, required
630        :param records: The records to upsert into the index.
631        :type records: List[Dict], required
632
633        Upsert records to a namespace. A record is a dictionary that contains eitiher an `id` or `_id`
634        field along with other fields that will be stored as metadata. The `id` or `_id` field is used
635        as the unique identifier for the record. At least one field in the record should correspond to
636        a field mapping in the index's embed configuration.
637
638        When records are upserted, Pinecone converts mapped fields into embeddings and upserts them into
639        the specified namespacce of the index.
640
641        ```python
642        import asyncio
643        from pinecone import (
644            Pinecone,
645            CloudProvider,
646            AwsRegion,
647            EmbedModel
648            IndexEmbed
649        )
650
651        async def main():
652            pc = Pinecone()
653            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
654                # upsert records
655                await idx.upsert_records(
656                    namespace="my-namespace",
657                    records=[
658                        {
659                            "_id": "test1",
660                            "my_text_field": "Apple is a popular fruit known for its sweetness and crisp texture.",
661                        },
662                        {
663                            "_id": "test2",
664                            "my_text_field": "The tech company Apple is known for its innovative products like the iPhone.",
665                        },
666                        {
667                            "_id": "test3",
668                            "my_text_field": "Many people enjoy eating apples as a healthy snack.",
669                        },
670                        {
671                            "_id": "test4",
672                            "my_text_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.",
673                        },
674                        {
675                            "_id": "test5",
676                            "my_text_field": "An apple a day keeps the doctor away, as the saying goes.",
677                        },
678                        {
679                            "_id": "test6",
680                            "my_text_field": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.",
681                        },
682                    ],
683                )
684
685                from pinecone import SearchQuery, SearchRerank, RerankModel
686
687                # search for similar records
688                response = await idx.search_records(
689                    namespace="my-namespace",
690                    query=SearchQuery(
691                        inputs={
692                            "text": "Apple corporation",
693                        },
694                        top_k=3,
695                    ),
696                    rerank=SearchRerank(
697                        model=RerankModel.Bge_Reranker_V2_M3,
698                        rank_fields=["my_text_field"],
699                        top_n=3,
700                    ),
701                )
702
703        asyncio.run(main())
704        ```
705        """
706        pass
707
708    @abstractmethod
709    async def search(
710        self,
711        namespace: str,
712        query: Union[SearchQueryTypedDict, SearchQuery],
713        rerank: Optional[Union[SearchRerankTypedDict, SearchRerank]] = None,
714        fields: Optional[List[str]] = ["*"],  # Default to returning all fields
715    ) -> SearchRecordsResponse:
716        """
717        :param namespace: The namespace in the index to search.
718        :type namespace: str, required
719        :param query: The SearchQuery to use for the search.
720        :type query: Union[Dict, SearchQuery], required
721        :param rerank: The SearchRerank to use with the search request.
722        :type rerank: Union[Dict, SearchRerank], optional
723        :return: The records that match the search.
724
725        Search for records.
726
727        This operation converts a query to a vector embedding and then searches a namespace. You
728        can optionally provide a reranking operation as part of the search.
729
730        ```python
731        import asyncio
732        from pinecone import (
733            Pinecone,
734            CloudProvider,
735            AwsRegion,
736            EmbedModel
737            IndexEmbed
738        )
739
740        async def main():
741            pc = Pinecone()
742            async with pc.IndexAsyncio(host="example-dojoi3u.svc.aped-4627-b74a.pinecone.io") as idx:
743                # upsert records
744                await idx.upsert_records(
745                    namespace="my-namespace",
746                    records=[
747                        {
748                            "_id": "test1",
749                            "my_text_field": "Apple is a popular fruit known for its sweetness and crisp texture.",
750                        },
751                        {
752                            "_id": "test2",
753                            "my_text_field": "The tech company Apple is known for its innovative products like the iPhone.",
754                        },
755                        {
756                            "_id": "test3",
757                            "my_text_field": "Many people enjoy eating apples as a healthy snack.",
758                        },
759                        {
760                            "_id": "test4",
761                            "my_text_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.",
762                        },
763                        {
764                            "_id": "test5",
765                            "my_text_field": "An apple a day keeps the doctor away, as the saying goes.",
766                        },
767                        {
768                            "_id": "test6",
769                            "my_text_field": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.",
770                        },
771                    ],
772                )
773
774                from pinecone import SearchQuery, SearchRerank, RerankModel
775
776                # search for similar records
777                response = await idx.search_records(
778                    namespace="my-namespace",
779                    query=SearchQuery(
780                        inputs={
781                            "text": "Apple corporation",
782                        },
783                        top_k=3,
784                    ),
785                    rerank=SearchRerank(
786                        model=RerankModel.Bge_Reranker_V2_M3,
787                        rank_fields=["my_text_field"],
788                        top_n=3,
789                    ),
790                )
791
792        asyncio.run(main())
793        ```
794
795        """
796        pass
797
798    @abstractmethod
799    async def search_records(
800        self,
801        namespace: str,
802        query: Union[SearchQueryTypedDict, SearchQuery],
803        rerank: Optional[Union[SearchRerankTypedDict, SearchRerank]] = None,
804        fields: Optional[List[str]] = ["*"],  # Default to returning all fields
805    ) -> SearchRecordsResponse:
806        """Alias of the search() method."""
807        pass