pinecone.control.pinecone_interface

  1from abc import ABC, abstractmethod
  2
  3from typing import Optional, Dict, Union
  4
  5
  6from pinecone.models import (
  7    ServerlessSpec,
  8    PodSpec,
  9    IndexList,
 10    CollectionList,
 11    IndexModel,
 12    IndexEmbed,
 13)
 14from pinecone.enums import (
 15    Metric,
 16    VectorType,
 17    DeletionProtection,
 18    PodType,
 19    CloudProvider,
 20    AwsRegion,
 21    GcpRegion,
 22    AzureRegion,
 23)
 24from .types import CreateIndexForModelEmbedTypedDict
 25
 26
 27class PineconeDBControlInterface(ABC):
 28    @abstractmethod
 29    def __init__(
 30        self,
 31        api_key: Optional[str] = None,
 32        host: Optional[str] = None,
 33        proxy_url: Optional[str] = None,
 34        proxy_headers: Optional[Dict[str, str]] = None,
 35        ssl_ca_certs: Optional[str] = None,
 36        ssl_verify: Optional[bool] = None,
 37        additional_headers: Optional[Dict[str, str]] = {},
 38        pool_threads: Optional[int] = 1,
 39        **kwargs,
 40    ):
 41        """
 42        The `Pinecone` class is the main entry point for interacting with Pinecone via this Python SDK.
 43        Instances of the `Pinecone` class are used to create, delete, and manage your indexes and collections. The class also holds inference functionality (embed, rerank) under the `inference` namespace.
 44        Methods which create or modify index and collection resources result in network calls to https://api.pinecone.io.
 45
 46        When you are ready to perform data operations on an index, you will need to instantiate an index client. Though the functionality of the index client is defined in a different
 47        class, it is instantiated through the `Index()` method in order for configurations to be shared between the two objects.
 48
 49        :param api_key: The API key to use for authentication. If not passed via kwarg, the API key will be read from the environment variable `PINECONE_API_KEY`.
 50        :type api_key: str, optional
 51        :param host: The control plane host. If unspecified, the host `api.pinecone.io` will be used.
 52        :type host: str, optional
 53        :param proxy_url: The URL of the proxy to use for the connection.
 54        :type proxy_url: str, optional
 55        :param proxy_headers: Additional headers to pass to the proxy. Use this if your proxy setup requires authentication.
 56        :type proxy_headers: Dict[str, str], optional
 57        :param ssl_ca_certs: The path to the SSL CA certificate bundle to use for the connection. This path should point to a file in PEM format. When not passed, the SDK will use the certificate bundle returned from `certifi.where()`.
 58        :type ssl_ca_certs: str, optional
 59        :param ssl_verify: SSL verification is performed by default, but can be disabled using the boolean flag when testing with Pinecone Local or troubleshooting a proxy setup. You should never run with SSL verification disabled in production.
 60        :type ssl_verify: bool, optional
 61        :param additional_headers: Additional headers to pass to the API. This is mainly to support internal testing at Pinecone. End users should not need to use this unless following specific instructions to do so.
 62        :type additional_headers: Dict[str, str], optional
 63        :param pool_threads: The number of threads to use for the ThreadPool when using methods that support the `async_req` keyword argument. The default number of threads is 5 * the number of CPUs in your execution environment.
 64        :type pool_threads: int, optional
 65
 66        ### Configuration with environment variables
 67
 68        If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`.
 69
 70        ```python
 71        from pinecone import Pinecone
 72
 73        pc = Pinecone()
 74        ```
 75
 76        ### Configuration with keyword arguments
 77
 78        If you prefer being more explicit in your code, you can also pass the API key as a keyword argument. This is also where you will pass additional configuration options such as proxy settings if you wish to use those.
 79
 80        ```python
 81        import os
 82        from pinecone import Pinecone
 83
 84        pc = Pinecone(
 85            api_key=os.environ.get("PINECONE_API_KEY"),
 86            host="https://api-staging.pinecone.io"
 87        )
 88        ```
 89
 90        ### Environment variables
 91
 92        The Pinecone client supports the following environment variables:
 93
 94        - `PINECONE_API_KEY`: The API key to use for authentication. If not passed via
 95        kwarg, the API key will be read from the environment variable `PINECONE_API_KEY`.
 96
 97        - `PINECONE_DEBUG_CURL`: When troubleshooting it can be very useful to run curl
 98        commands against the control plane API to see exactly what data is being sent
 99        and received without all the abstractions and transformations applied by the Python
100        SDK. If you set this environment variable to `true`, the Pinecone client will use
101        request parameters to print out an equivalent curl command that you can run yourself
102        or share with Pinecone support. **Be very careful with this option, as it will print out
103        your API key** which forms part of a required authentication header. The main use of
104        is to help evaluate whether a problem you are experiencing is due to the API's behavior
105        or the behavior of the SDK itself.
106
107        ### Proxy configuration
108
109        If your network setup requires you to interact with Pinecone via a proxy, you will need
110        to pass additional configuration using optional keyword parameters. These optional parameters
111        are forwarded to `urllib3`, which is the underlying library currently used by the Pinecone client to
112        make HTTP requests. You may find it helpful to refer to the
113        [urllib3 documentation on working with proxies](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#http-and-https-proxies)
114        while troubleshooting these settings.
115
116        Here is a basic example:
117
118        ```python
119        from pinecone import Pinecone
120
121        pc = Pinecone(
122            api_key='YOUR_API_KEY',
123            proxy_url='https://your-proxy.com'
124        )
125
126        pc.list_indexes()
127        ```
128
129        If your proxy requires authentication, you can pass those values in a header dictionary using the `proxy_headers` parameter.
130
131        ```python
132        from pinecone import Pinecone
133        import urllib3 import make_headers
134
135        pc = Pinecone(
136            api_key='YOUR_API_KEY',
137            proxy_url='https://your-proxy.com',
138            proxy_headers=make_headers(proxy_basic_auth='username:password')
139        )
140
141        pc.list_indexes()
142        ```
143
144        ### Using proxies with self-signed certificates
145
146        By default the Pinecone Python client will perform SSL certificate verification
147        using the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/certifi/) package.
148        If your proxy server is using a self-signed certificate, you will need to pass the path to the certificate
149        in PEM format using the `ssl_ca_certs` parameter.
150
151        ```python
152        from pinecone import Pinecone
153        import urllib3 import make_headers
154
155        pc = Pinecone(
156            api_key='YOUR_API_KEY',
157            proxy_url='https://your-proxy.com',
158            proxy_headers=make_headers(proxy_basic_auth='username:password'),
159            ssl_ca_certs='path/to/cert-bundle.pem'
160        )
161
162        pc.list_indexes()
163        ```
164
165        ### Disabling SSL verification
166
167        If you would like to disable SSL verification, you can pass the `ssl_verify`
168        parameter with a value of `False`. We do not recommend going to production with SSL verification disabled.
169
170        ```python
171        from pinecone import Pinecone
172        import urllib3 import make_headers
173
174        pc = Pinecone(
175            api_key='YOUR_API_KEY',
176            proxy_url='https://your-proxy.com',
177            proxy_headers=make_headers(proxy_basic_auth='username:password'),
178            ssl_ca_certs='path/to/cert-bundle.pem',
179            ssl_verify=False
180        )
181
182        pc.list_indexes()
183
184        ```
185        """
186
187    pass
188
189    @abstractmethod
190    def create_index(
191        self,
192        name: str,
193        spec: Union[Dict, ServerlessSpec, PodSpec],
194        dimension: Optional[int],
195        metric: Optional[Union[Metric, str]] = Metric.COSINE,
196        timeout: Optional[int] = None,
197        deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED,
198        vector_type: Optional[Union[VectorType, str]] = VectorType.DENSE,
199        tags: Optional[Dict[str, str]] = None,
200    ) -> IndexModel:
201        """Creates a Pinecone index.
202
203        :param name: The name of the index to create. Must be unique within your project and
204            cannot be changed once created. Allowed characters are lowercase letters, numbers,
205            and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters.
206        :type name: str
207        :param metric: Type of similarity metric used in the vector index when querying, one of `{"cosine", "dotproduct", "euclidean"}`.
208        :type metric: str, optional
209        :param spec: A dictionary containing configurations describing how the index should be deployed. For serverless indexes,
210            specify region and cloud. For pod indexes, specify replicas, shards, pods, pod_type, metadata_config, and source_collection.
211            Alternatively, use the `ServerlessSpec` or `PodSpec` objects to specify these configurations.
212        :type spec: Dict
213        :param dimension: If you are creating an index with `vector_type="dense"` (which is the default), you need to specify `dimension` to indicate the size of your vectors.
214            This should match the dimension of the embeddings you will be inserting. For example, if you are using
215            OpenAI's CLIP model, you should use `dimension=1536`. Dimension is a required field when
216            creating an index with `vector_type="dense"` and should not be passed when `vector_type="sparse"`.
217        :type dimension: int
218        :type timeout: int, optional
219        :param timeout: Specify the number of seconds to wait until index gets ready. If None, wait indefinitely; if >=0, time out after this many seconds;
220            if -1, return immediately and do not wait.
221        :param deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted.
222        :type deletion_protection: Optional[Literal["enabled", "disabled"]]
223        :param vector_type: The type of vectors to be stored in the index. One of `{"dense", "sparse"}`.
224        :type vector_type: str, optional
225        :param tags: Tags are key-value pairs you can attach to indexes to better understand, organize, and identify your resources. Some example use cases include tagging indexes with the name of the model that generated the embeddings, the date the index was created, or the purpose of the index.
226        :type tags: Optional[Dict[str, str]]
227        :return: A `IndexModel` instance containing a description of the index that was created.
228
229        ### Creating a serverless index
230
231        ```python
232        import os
233        from pinecone import (
234            Pinecone,
235            ServerlessSpec,
236            CloudProvider,
237            AwsRegion,
238            Metric,
239            DeletionProtection,
240            VectorType
241        )
242
243        pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
244
245        pc.create_index(
246            name="my_index",
247            dimension=1536,
248            metric=Metric.COSINE,
249            spec=ServerlessSpec(
250                cloud=CloudProvider.AWS,
251                region=AwsRegion.US_WEST_2
252            ),
253            deletion_protection=DeletionProtection.DISABLED,
254            vector_type=VectorType.DENSE,
255            tags={
256                "model": "clip",
257                "app": "image-search",
258                "env": "testing"
259            }
260        )
261        ```
262
263        ### Creating a pod index
264
265        ```python
266        import os
267        from pinecone import (
268            Pinecone,
269            PodSpec,
270            PodIndexEnvironment,
271            PodType,
272            Metric,
273            DeletionProtection,
274            VectorType
275        )
276
277        pc = Pinecone(api_key=os.environ.get("PINECONE_API_KEY"))
278
279        pc.create_index(
280            name="my_index",
281            dimension=1536,
282            metric=Metric.COSINE,
283            spec=PodSpec(
284                environment=PodIndexEnvironment.US_EAST4_GCP,
285                pod_type=PodType.P1_X1
286            ),
287            deletion_protection=DeletionProtection.DISABLED,
288            tags={
289                "model": "clip",
290                "app": "image-search",
291                "env": "testing"
292            }
293        )
294        ```
295        """
296        pass
297
298    @abstractmethod
299    def create_index_for_model(
300        self,
301        name: str,
302        cloud: Union[CloudProvider, str],
303        region: Union[AwsRegion, GcpRegion, AzureRegion, str],
304        embed: Union[IndexEmbed, CreateIndexForModelEmbedTypedDict],
305        tags: Optional[Dict[str, str]] = None,
306        deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED,
307        timeout: Optional[int] = None,
308    ) -> IndexModel:
309        """
310        :param name: The name of the index to create. Must be unique within your project and
311            cannot be changed once created. Allowed characters are lowercase letters, numbers,
312            and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters.
313        :type name: str
314        :param cloud: The cloud provider to use for the index. One of `{"aws", "gcp", "azure"}`.
315        :type cloud: str
316        :param region: The region to use for the index. Enum objects `AwsRegion`, `GcpRegion`, and `AzureRegion` are also available to help you quickly set these parameters, but may not be up to date as new regions become available.
317        :type region: str
318        :param embed: The embedding configuration for the index. This param accepts a dictionary or an instance of the `IndexEmbed` object.
319        :type embed: Union[Dict, IndexEmbed]
320        :param tags: Tags are key-value pairs you can attach to indexes to better understand, organize, and identify your resources. Some example use cases include tagging indexes with the name of the model that generated the embeddings, the date the index was created, or the purpose of the index.
321        :type tags: Optional[Dict[str, str]]
322        :param deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted. This setting can be changed with `configure_index`.
323        :type deletion_protection: Optional[Literal["enabled", "disabled"]]
324        :type timeout: Optional[int]
325        :param timeout: Specify the number of seconds to wait until index is ready to receive data. If None, wait indefinitely; if >=0, time out after this many seconds;
326            if -1, return immediately and do not wait.
327        :return: A description of the index that was created.
328        :rtype: IndexModel
329
330        This method is used to create a Serverless index that is configured for use with Pinecone's integrated inference models.
331
332        The resulting index can be described, listed, configured, and deleted like any other Pinecone index with the `describe_index`, `list_indexes`, `configure_index`, and `delete_index` methods.
333
334        After the model is created, you can upsert records into the index with the `upsert_records` method, and search your records with the `search` method.
335
336        ```python
337        from pinecone import (
338            Pinecone,
339            IndexEmbed,
340            CloudProvider,
341            AwsRegion,
342            EmbedModel,
343            Metric,
344        )
345
346        pc = Pinecone()
347
348        if not pc.has_index("book-search"):
349            desc = await pc.create_index_for_model(
350                name="book-search",
351                cloud=CloudProvider.AWS,
352                region=AwsRegion.US_EAST_1,
353                embed=IndexEmbed(
354                    model=EmbedModel.Multilingual_E5_Large,
355                    metric=Metric.COSINE,
356                    field_map={
357                        "text": "description",
358                    },
359                )
360            )
361        ```
362
363        To see the available cloud regions, see this [Pinecone documentation](https://docs.pinecone.io/troubleshooting/available-cloud-regions) page.
364
365        See the [Model Gallery](https://docs.pinecone.io/models/overview) to learn about available models.
366        """
367        pass
368
369    @abstractmethod
370    def delete_index(self, name: str, timeout: Optional[int] = None):
371        """
372        :param name: the name of the index.
373        :type name: str
374        :param timeout: Number of seconds to poll status checking whether the index has been deleted. If None,
375            wait indefinitely; if >=0, time out after this many seconds;
376            if -1, return immediately and do not wait.
377        :type timeout: int, optional
378
379        Deletes a Pinecone index.
380
381        Deleting an index is an irreversible operation. All data in the index will be lost.
382        When you use this command, a request is sent to the Pinecone control plane to delete
383        the index, but the termination is not synchronous because resources take a few moments to
384        be released.
385
386        By default the `delete_index` method will block until polling of the `describe_index` method
387        shows that the delete operation has completed. If you prefer to return immediately and not
388        wait for the index to be deleted, you can pass `timeout=-1` to the method.
389
390        After the delete request is submitted, polling `describe_index` will show that the index
391        transitions into a `Terminating` state before eventually resulting in a 404 after it has been removed.
392
393        This operation can fail if the index is configured with `deletion_protection="enabled"`.
394        In this case, you will need to call `configure_index` to disable deletion protection before
395        you can delete the index.
396
397        ```python
398        from pinecone import Pinecone
399
400        pc = Pinecone()
401
402        index_name = "my_index"
403        desc = pc.describe_index(name=index_name)
404
405        if desc.deletion_protection == "enabled":
406            # If for some reason deletion protection is enabled, you will need to disable it first
407            # before you can delete the index. But use caution as this operation is not reversible
408            # and if somebody enabled deletion protection, they probably had a good reason.
409            pc.configure_index(name=index_name, deletion_protection="disabled")
410
411        pc.delete_index(name=index_name)
412        ```
413        """
414        pass
415
416    @abstractmethod
417    def list_indexes(self) -> IndexList:
418        """
419        :return: Returns an `IndexList` object, which is iterable and contains a
420            list of `IndexModel` objects. The `IndexList` also has a convenience method `names()`
421            which returns a list of index names for situations where you just want to iterate over
422            all index names.
423
424        Lists all indexes in your project.
425
426        The results include a description of all indexes in your project, including the
427        index name, dimension, metric, status, and spec.
428
429        If you simply want to check whether an index exists, see the `has_index()` convenience method.
430
431        You can use the `list_indexes()` method to iterate over descriptions of every index in your project.
432
433        ```python
434        from pinecone import Pinecone
435
436        pc = Pinecone()
437
438        for index in pc.list_indexes():
439            print(index.name)
440            print(index.dimension)
441            print(index.metric)
442            print(index.status)
443            print(index.host)
444            print(index.spec)
445        ```
446        """
447        pass
448
449    @abstractmethod
450    def describe_index(self, name: str) -> IndexModel:
451        """
452        :param name: the name of the index to describe.
453        :return: Returns an `IndexModel` object
454        which gives access to properties such as the
455        index name, dimension, metric, host url, status,
456        and spec.
457
458        Describes a Pinecone index.
459
460        ### Getting your index host url
461
462        In a real production situation, you probably want to
463        store the host url in an environment variable so you
464        don't have to call describe_index and re-fetch it
465        every time you want to use the index. But this example
466        shows how to get the value from the API using describe_index.
467
468        ```python
469        from pinecone import Pinecone, Index
470
471        pc = Pinecone()
472
473        index_name="my_index"
474        description = pc.describe_index(name=index_name)
475        print(description)
476        # {
477        #     "name": "my_index",
478        #     "metric": "cosine",
479        #     "host": "my_index-dojoi3u.svc.aped-4627-b74a.pinecone.io",
480        #     "spec": {
481        #         "serverless": {
482        #             "cloud": "aws",
483        #             "region": "us-east-1"
484        #         }
485        #     },
486        #     "status": {
487        #         "ready": true,
488        #         "state": "Ready"
489        #     },
490        #     "vector_type": "dense",
491        #     "dimension": 1024,
492        #     "deletion_protection": "enabled",
493        #     "tags": {
494        #         "environment": "production"
495        #     }
496        # }
497
498        print(f"Your index is hosted at {description.host}")
499
500        index = pc.Index(host=description.host)
501        index.upsert(vectors=[...])
502        ```
503        """
504        pass
505
506    @abstractmethod
507    def has_index(self, name: str) -> bool:
508        """
509        :param name: The name of the index to check for existence.
510        :return: Returns `True` if the index exists, `False` otherwise.
511
512        Checks if a Pinecone index exists.
513
514        ```python
515        from pinecone import Pinecone, ServerlessSpec
516
517        pc = Pinecone()
518
519        index_name = "my_index"
520        if not pc.has_index(index_name):
521            print("Index does not exist, creating...")
522            pc.create_index(
523                name=index_name,
524                dimension=768,
525                metric="cosine",
526                spec=ServerlessSpec(cloud="aws", region="us-west-2")
527            )
528        ```
529        """
530        pass
531
532    @abstractmethod
533    def configure_index(
534        self,
535        name: str,
536        replicas: Optional[int] = None,
537        pod_type: Optional[Union[PodType, str]] = None,
538        deletion_protection: Optional[Union[DeletionProtection, str]] = None,
539        tags: Optional[Dict[str, str]] = None,
540    ):
541        """
542        :param: name: the name of the Index
543        :param: replicas: the desired number of replicas, lowest value is 0.
544        :param: pod_type: the new pod_type for the index. To learn more about the
545            available pod types, please see [Understanding Indexes](https://docs.pinecone.io/docs/indexes)
546        :param: deletion_protection: If set to 'enabled', the index cannot be deleted. If 'disabled', the index can be deleted.
547        :param: tags: A dictionary of tags to apply to the index. Tags are key-value pairs that can be used to organize and manage indexes. To remove a tag, set the value to "". Tags passed to configure_index will be merged with existing tags and any with the value empty string will be removed.
548
549        This method is used to modify an index's configuration. It can be used to:
550
551        - Scale a pod-based index horizontally using `replicas`
552        - Scale a pod-based index vertically using `pod_type`
553        - Enable or disable deletion protection using `deletion_protection`
554        - Add, change, or remove tags using `tags`
555
556        ## Scaling pod-based indexes
557
558        To scale your pod-based index, you pass a `replicas` and/or `pod_type` param to the `configure_index` method. `pod_type` may be a string or a value from the `PodType` enum.
559
560        ```python
561        from pinecone import Pinecone, PodType
562
563        pc = Pinecone()
564        pc.configure_index(
565            name="my_index",
566            replicas=2,
567            pod_type=PodType.P1_X2
568        )
569        ```
570
571        After providing these new configurations, you must call `describe_index` to see the status of the index as the changes are applied.
572
573        ## Enabling or disabling deletion protection
574
575        To enable or disable deletion protection, pass the `deletion_protection` parameter to the `configure_index` method. When deletion protection
576        is enabled, the index cannot be deleted with the `delete_index` method.
577
578        ```python
579        from pinecone import Pinecone, DeletionProtection
580
581        pc = Pinecone()
582
583        # Enable deletion protection
584        pc.configure_index(
585            name="my_index",
586            deletion_protection=DeletionProtection.ENABLED
587        )
588
589        # Call describe_index to see the change was applied.
590        assert pc.describe_index("my_index").deletion_protection == "enabled"
591
592        # Disable deletion protection
593        pc.configure_index(
594            name="my_index",
595            deletion_protection=DeletionProtection.DISABLED
596        )
597        ```
598
599        ## Adding, changing, or removing tags
600
601        To add, change, or remove tags, pass the `tags` parameter to the `configure_index` method. When tags are passed using `configure_index`,
602        they are merged with any existing tags already on the index. To remove a tag, set the value of the key to an empty string.
603
604        ```python
605        from pinecone import Pinecone
606
607        pc = Pinecone()
608
609        # Add a tag
610        pc.configure_index(name="my_index", tags={"environment": "staging"})
611
612        # Change a tag
613        pc.configure_index(name="my_index", tags={"environment": "production"})
614
615        # Remove a tag
616        pc.configure_index(name="my_index", tags={"environment": ""})
617
618        # Call describe_index to view the tags are changed
619        print(pc.describe_index("my_index").tags)
620        ```
621        """
622        pass
623
624    @abstractmethod
625    def create_collection(self, name: str, source: str):
626        """Create a collection from a pod-based index
627
628        :param name: Name of the collection
629        :param source: Name of the source index
630        """
631        pass
632
633    @abstractmethod
634    def list_collections(self) -> CollectionList:
635        """List all collections
636
637        ```python
638        from pinecone import Pinecone
639
640        pc = Pinecone()
641
642        for collection in pc.list_collections():
643            print(collection.name)
644            print(collection.source)
645
646        # You can also iterate specifically over the collection
647        # names with the .names() helper.
648        collection_name="my_collection"
649        for collection_name in pc.list_collections().names():
650            print(collection_name)
651        ```
652        """
653        pass
654
655    @abstractmethod
656    def delete_collection(self, name: str) -> None:
657        """
658        :param name: The name of the collection to delete.
659
660        Deletes a collection.
661
662        Deleting a collection is an irreversible operation. All data
663        in the collection will be lost.
664
665        This method tells Pinecone you would like to delete a collection,
666        but it takes a few moments to complete the operation. Use the
667        `describe_collection()` method to confirm that the collection
668        has been deleted.
669
670        ```python
671        from pinecone import Pinecone
672
673        pc = Pinecone()
674
675        pc.delete_collection(name="my_collection")
676        ```
677        """
678        pass
679
680    @abstractmethod
681    def describe_collection(self, name: str):
682        """Describes a collection.
683        :param: The name of the collection
684        :return: Description of the collection
685
686        ```python
687        from pinecone import Pinecone
688
689        pc = Pinecone()
690
691        description = pc.describe_collection("my_collection")
692        print(description.name)
693        print(description.source)
694        print(description.status)
695        print(description.size)
696        ```
697        """
698        pass
699
700    @abstractmethod
701    def Index(self, name: str = "", host: str = "", **kwargs):
702        """
703        :param name: The name of the index to target. If you specify the name of the index, the client will
704            fetch the host url from the Pinecone control plane.
705        :param host: The host url of the index to target. If you specify the host url, the client will use
706            the host url directly without making any additional calls to the control plane.
707        :param pool_threads: The number of threads to use when making parallel requests by calling index methods with optional kwarg async_req=True, or using methods that make use of thread-based parallelism automatically such as query_namespaces().
708        :param connection_pool_maxsize: The maximum number of connections to keep in the connection pool.
709        :return: An instance of the `Index` class.
710
711        Target an index for data operations.
712
713        ### Target an index by host url
714
715        In production situations, you want to uspert or query your data as quickly
716        as possible. If you know in advance the host url of your index, you can
717        eliminate a round trip to the Pinecone control plane by specifying the
718        host of the index. If instead you pass the name of the index, the client
719        will need to make an additional call to api.pinecone.io to get the host url
720        before any data operations can take place.
721
722        ```python
723        import os
724        from pinecone import Pinecone
725
726        api_key = os.environ.get("PINECONE_API_KEY")
727        index_host = os.environ.get("PINECONE_INDEX_HOST")
728
729        pc = Pinecone(api_key=api_key)
730        index = pc.Index(host=index_host)
731
732        # Now you're ready to perform data operations
733        index.query(vector=[...], top_k=10)
734        ```
735
736        To find your host url, you can use the describe_index method to call api.pinecone.io.
737        The host url is returned in the response. Or, alternatively, the
738        host is displayed in the Pinecone web console.
739
740        ```python
741        import os
742        from pinecone import Pinecone
743
744        pc = Pinecone(
745            api_key=os.environ.get("PINECONE_API_KEY")
746        )
747
748        host = pc.describe_index('index-name').host
749        ```
750
751        ### Target an index by name (not recommended for production)
752
753        For more casual usage, such as when you are playing and exploring with Pinecone
754        in a notebook setting, you can also target an index by name. If you use this
755        approach, the client may need to perform an extra call to the Pinecone control
756        plane to get the host url on your behalf to get the index host.
757
758        The client will cache the index host for future use whenever it is seen, so you
759        will only incur the overhead of only one call. But this approach is not
760        recommended for production usage because it introduces an unnecessary runtime
761        dependency on api.pinecone.io.
762
763        ```python
764        import os
765        from pinecone import Pinecone, ServerlessSpec
766
767        api_key = os.environ.get("PINECONE_API_KEY")
768
769        pc = Pinecone(api_key=api_key)
770        pc.create_index(
771            name='my_index',
772            dimension=1536,
773            metric='cosine',
774            spec=ServerlessSpec(cloud='aws', region='us-west-2')
775        )
776        index = pc.Index('my_index')
777
778        # Now you're ready to perform data operations
779        index.query(vector=[...], top_k=10)
780        ```
781        """
782        pass
783
784    def IndexAsyncio(self, host: str, **kwargs):
785        """Build an asyncio-compatible Index object.
786
787        :param host: The host url of the index to target. You can find this url in the Pinecone
788            web console or by calling describe_index method of `Pinecone` or `PineconeAsyncio`.
789
790        :return: An instance of the `IndexAsyncio` class.
791        """
792        pass