pinecone.grpc.pinecone

  1from ..control.pinecone import Pinecone
  2from ..config.config import ConfigBuilder
  3from .index_grpc import GRPCIndex
  4
  5
  6class PineconeGRPC(Pinecone):
  7    """
  8    An alternative version of the Pinecone client that uses gRPC instead of HTTP for
  9    data operations.
 10
 11    ### Installing the gRPC client
 12
 13    You must install extra dependencies in order to install the GRPC client.
 14
 15    #### Installing with pip
 16
 17    ```bash
 18    # Install the latest version
 19    pip3 install pinecone[grpc]
 20
 21    # Install a specific version
 22    pip3 install "pinecone[grpc]"==3.0.0
 23    ```
 24
 25    #### Installing with poetry
 26
 27    ```bash
 28    # Install the latest version
 29    poetry add pinecone --extras grpc
 30
 31    # Install a specific version
 32    poetry add pinecone==3.0.0 --extras grpc
 33    ```
 34
 35    ### Using the gRPC client
 36
 37    ```python
 38    import os
 39    from pinecone.grpc import PineconeGRPC
 40
 41    client = PineconeGRPC(api_key=os.environ.get("PINECONE_API_KEY"))
 42
 43    # From this point on, usage is identical to the HTTP client.
 44    index = client.Index("my-index", host=os.environ("PINECONE_INDEX_HOST"))
 45    index.query(...)
 46    ```
 47
 48    """
 49
 50    def Index(self, name: str = "", host: str = "", **kwargs):
 51        """
 52        Target an index for data operations.
 53
 54        ### Target an index by host url
 55
 56        In production situations, you want to uspert or query your data as quickly
 57        as possible. If you know in advance the host url of your index, you can
 58        eliminate a round trip to the Pinecone control plane by specifying the
 59        host of the index.
 60
 61        ```python
 62        import os
 63        from pinecone.grpc import PineconeGRPC
 64
 65        api_key = os.environ.get("PINECONE_API_KEY")
 66        index_host = os.environ.get("PINECONE_INDEX_HOST")
 67
 68        pc = PineconeGRPC(api_key=api_key)
 69        index = pc.Index(host=index_host)
 70
 71        # Now you're ready to perform data operations
 72        index.query(vector=[...], top_k=10)
 73        ```
 74
 75        To find your host url, you can use the Pinecone control plane to describe
 76        the index. The host url is returned in the response. Or, alternatively, the
 77        host is displayed in the Pinecone web console.
 78
 79        ```python
 80        import os
 81        from pinecone import Pinecone
 82
 83        pc = Pinecone(
 84            api_key=os.environ.get("PINECONE_API_KEY")
 85        )
 86
 87        host = pc.describe_index('index-name').host
 88        ```
 89
 90        ### Target an index by name (not recommended for production)
 91
 92        For more casual usage, such as when you are playing and exploring with Pinecone
 93        in a notebook setting, you can also target an index by name. If you use this
 94        approach, the client may need to perform an extra call to the Pinecone control
 95        plane to get the host url on your behalf to get the index host.
 96
 97        The client will cache the index host for future use whenever it is seen, so you
 98        will only incur the overhead of only one call. But this approach is not
 99        recommended for production usage.
100
101        ```python
102        import os
103        from pinecone import ServerlessSpec
104        from pinecone.grpc import PineconeGRPC
105
106        api_key = os.environ.get("PINECONE_API_KEY")
107
108        pc = PineconeGRPC(api_key=api_key)
109        pc.create_index(
110            name='my-index',
111            dimension=1536,
112            metric='cosine',
113            spec=ServerlessSpec(cloud='aws', region='us-west-2')
114        )
115        index = pc.Index('my-index')
116
117        # Now you're ready to perform data operations
118        index.query(vector=[...], top_k=10)
119        ```
120        """
121        if name == "" and host == "":
122            raise ValueError("Either name or host must be specified")
123
124        # Use host if it is provided, otherwise get host from describe_index
125        index_host = host or self.index_host_store.get_host(self.index_api, self.config, name)
126
127        config = ConfigBuilder.build(
128            api_key=self.config.api_key,
129            host=index_host,
130            source_tag=self.config.source_tag,
131            proxy_url=self.config.proxy_url,
132            ssl_ca_certs=self.config.ssl_ca_certs,
133        )
134        return GRPCIndex(index_name=name, config=config, **kwargs)