pinecone.control.pinecone_interface_asyncio
1from abc import ABC, abstractmethod 2 3from typing import Optional, Dict, Union 4 5 6from pinecone.config import Config 7 8from pinecone.core.openapi.db_control.api.manage_indexes_api import ManageIndexesApi 9 10 11from pinecone.models import ( 12 ServerlessSpec, 13 PodSpec, 14 IndexList, 15 CollectionList, 16 IndexModel, 17 IndexEmbed, 18) 19from pinecone.enums import ( 20 Metric, 21 VectorType, 22 DeletionProtection, 23 PodType, 24 CloudProvider, 25 AwsRegion, 26 GcpRegion, 27 AzureRegion, 28) 29from .types import CreateIndexForModelEmbedTypedDict 30 31 32class PineconeAsyncioDBControlInterface(ABC): 33 @abstractmethod 34 def __init__( 35 self, 36 api_key: Optional[str] = None, 37 host: Optional[str] = None, 38 proxy_url: Optional[str] = None, 39 proxy_headers: Optional[Dict[str, str]] = None, 40 ssl_ca_certs: Optional[str] = None, 41 ssl_verify: Optional[bool] = None, 42 config: Optional[Config] = None, 43 additional_headers: Optional[Dict[str, str]] = {}, 44 pool_threads: Optional[int] = 1, 45 index_api: Optional[ManageIndexesApi] = None, 46 **kwargs, 47 ): 48 """ 49 The `PineconeAsyncio` class is the main entry point for interacting with Pinecone using asyncio. 50 It is used to create, delete, and manage your indexes and collections. Except for needing to use 51 `async with` when instantiating the client and `await` when calling its methods, the functionality 52 provided by this class is extremely similar to the functionality of the `Pinecone` class. 53 54 :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`. 55 :type api_key: str, optional 56 :param host: The control plane host to connect to. 57 :type host: str, optional 58 :param proxy_url: The URL of the proxy to use for the connection. Default: `None` 59 :type proxy_url: str, optional 60 :param proxy_headers: Additional headers to pass to the proxy. Use this if your proxy setup requires authentication. Default: `{}` 61 :type proxy_headers: Dict[str, str], optional 62 :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. Default: `None` 63 :type ssl_ca_certs: str, optional 64 :param ssl_verify: SSL verification is performed by default, but can be disabled using the boolean flag. Default: `True` 65 :type ssl_verify: bool, optional 66 :param config: A `pinecone.config.Config` object. If passed, the `api_key` and `host` parameters will be ignored. 67 :type config: pinecone.config.Config, optional 68 :param additional_headers: Additional headers to pass to the API. Default: `{}` 69 :type additional_headers: Dict[str, str], optional 70 71 72 ### Managing the async context 73 74 The `PineconeAsyncio` class relies on an underlying `aiohttp` `ClientSession` to make asynchronous HTTP requests. To ensure that the session is properly closed, you 75 should use the `async with` syntax when creating a `PineconeAsyncio` object. This will ensure that the session is properly closed when the context is exited. 76 77 ```python 78 import asyncio 79 from pinecone import PineconeAsyncio 80 81 async def main(): 82 async with PineconeAsyncio(api_key='YOUR_API_KEY') as pc: 83 # Do async things 84 index_list = await pc.list_indexes() 85 86 asyncio.run(main()) 87 ``` 88 89 As an alternative, if you prefer to avoid code with a nested appearance and are willing to manage cleanup yourself, you can await the `close()` method to close the session when you are done. 90 91 ```python 92 import asyncio 93 from pinecone import PineconeAsyncio 94 95 async def main(): 96 pc = PineconeAsyncio(api_key='YOUR_API_KEY') 97 98 # Do async things 99 index_list = await pc.list_indexes() 100 101 # You're responsible for calling this yourself 102 await pc.close() 103 104 asyncio.run(main()) 105 ``` 106 107 Failing to do this may result in error messages appearing from the underlyling aiohttp library. 108 109 ### Configuration with environment variables 110 111 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 112 113 ```python 114 import asyncio 115 from pinecone import PineconeAsyncio 116 117 async def main(): 118 async with PineconeAsyncio() as pc: 119 # Do async things 120 index_list = await pc.list_indexes() 121 122 asyncio.run(main()) 123 ``` 124 125 ### Configuration with keyword arguments 126 127 If you prefer being more explicit in your code, you can also pass the API as 128 129 ### Configuration with environment variables 130 131 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 132 133 ```python 134 import asyncio 135 from pinecone import PineconeAsyncio 136 137 async def main(): 138 async with PineconeAsyncio() as pc: 139 # Do async things 140 index_list = await pc.list_indexes() 141 142 asyncio.run(main()) 143 ``` 144 145 ### Configuration with keyword arguments 146 147 If you prefer being more explicit in your code, you can also pass the API as 148 149 150 151 ### Configuration with environment variables 152 153 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 154 155 ```python 156 import asyncio 157 from pinecone import PineconeAsyncio 158 159 async def main(): 160 async with PineconeAsyncio() as pc: 161 # Do async things 162 index_list = await pc.list_indexes() 163 164 asyncio.run(main()) 165 ``` 166 167 ### Configuration with keyword arguments 168 169 If you prefer being more explicit in your code, you can also pass the API as a keyword argument. 170 171 ```python 172 import os 173 import asyncio 174 from pinecone import PineconeAsyncio 175 176 async def main(): 177 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 178 # Do async things 179 index_list = await pc.list_indexes() 180 181 asyncio.run(main()) 182 ``` 183 184 ### Environment variables 185 186 The Pinecone client supports the following environment variables: 187 188 - `PINECONE_API_KEY`: The API key to use for authentication. If not passed via 189 kwarg, the API key will be read from the environment variable `PINECONE_API_KEY`. 190 191 ### Proxy configuration 192 193 If your network setup requires you to interact with Pinecone via a proxy, you will need 194 to pass additional configuration using optional keyword parameters. These optional parameters 195 are used to configure an SSL context and passed to `aiohttp`, which is the underlying library 196 currently used by the PineconeAsyncio client to make HTTP requests. 197 198 Here is a basic example: 199 200 ```python 201 import asyncio 202 from pinecone import PineconeAsyncio 203 204 async def main(): 205 async with PineconeAsyncio( 206 api_key='YOUR_API_KEY', 207 proxy_url='https://your-proxy.com' 208 ) as pc: 209 # Do async things 210 index_list = await pc.list_indexes() 211 212 asyncio.run(main()) 213 ``` 214 215 ### Using proxies with self-signed certificates 216 217 By default the Pinecone Python client will perform SSL certificate verification 218 using the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/certifi/) package. 219 If your proxy server is using a self-signed certificate, you will need to pass the path to the certificate 220 in PEM format using the `ssl_ca_certs` parameter. 221 222 ```python 223 import asyncio 224 from pinecone import PineconeAsyncio 225 226 async def main(): 227 async with PineconeAsyncio( 228 api_key='YOUR_API_KEY', 229 proxy_url='https://your-proxy.com', 230 ssl_ca_certs='path/to/cert-bundle.pem' 231 ) as pc: 232 # Do async things 233 await pc.list_indexes() 234 235 asyncio.run(main()) 236 ``` 237 238 ### Disabling SSL verification 239 240 If you would like to disable SSL verification, you can pass the `ssl_verify` 241 parameter with a value of `False`. We do not recommend going to production with SSL verification disabled 242 but there are situations where this is useful such as testing with Pinecone Local running in a docker 243 container. 244 245 ```python 246 import asyncio 247 from pinecone import PineconeAsyncio 248 249 async def main(): 250 async with PineconeAsyncio( 251 api_key='YOUR_API_KEY', 252 ssl_verify=False 253 ) as pc: 254 if not await pc.has_index('my_index'): 255 await pc.create_index( 256 name='my_index', 257 dimension=1536, 258 metric='cosine', 259 spec=ServerlessSpec(cloud='aws', region='us-west-2') 260 ) 261 262 asyncio.run(main()) 263 ``` 264 265 ### Passing additional headers 266 267 If you need to pass additional headers with each request to the Pinecone API, you can do so using the 268 `additional_headers` parameter. This is primarily for internal testing and end-users shouldn't need to 269 do this unless specifically instructed to do so. 270 271 ```python 272 import asyncio 273 from pinecone import PineconeAsyncio 274 275 async def main(): 276 async with PineconeAsyncio( 277 api_key='YOUR_API_KEY', 278 host='https://api-staging.pinecone.io', 279 additional_headers={'X-My-Header': 'my-value'} 280 ) as pc: 281 # Do async things 282 await pc.list_indexes() 283 284 asyncio.run(main()) 285 ``` 286 """ 287 288 pass 289 290 @abstractmethod 291 async def create_index( 292 self, 293 name: str, 294 spec: Union[Dict, ServerlessSpec, PodSpec], 295 dimension: Optional[int], 296 metric: Optional[Union[Metric, str]] = Metric.COSINE, 297 timeout: Optional[int] = None, 298 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 299 vector_type: Optional[Union[VectorType, str]] = VectorType.DENSE, 300 tags: Optional[Dict[str, str]] = None, 301 ): 302 """Creates a Pinecone index. 303 304 :param name: The name of the index to create. Must be unique within your project and 305 cannot be changed once created. Allowed characters are lowercase letters, numbers, 306 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 307 :type name: str 308 :param metric: Type of similarity metric used in the vector index when querying, one of `{"cosine", "dotproduct", "euclidean"}`. 309 :type metric: str, optional 310 :param spec: A dictionary containing configurations describing how the index should be deployed. For serverless indexes, 311 specify region and cloud. For pod indexes, specify replicas, shards, pods, pod_type, metadata_config, and source_collection. 312 Alternatively, use the `ServerlessSpec` or `PodSpec` objects to specify these configurations. 313 :type spec: Dict 314 :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. 315 This should match the dimension of the embeddings you will be inserting. For example, if you are using 316 OpenAI's CLIP model, you should use `dimension=1536`. Dimension is a required field when 317 creating an index with `vector_type="dense"` and should not be passed when `vector_type="sparse"`. 318 :type dimension: int 319 :type timeout: int, optional 320 :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; 321 if -1, return immediately and do not wait. 322 :param deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted. 323 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 324 :param vector_type: The type of vectors to be stored in the index. One of `{"dense", "sparse"}`. 325 :type vector_type: str, optional 326 :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. 327 :type tags: Optional[Dict[str, str]] 328 :return: A `IndexModel` instance containing a description of the index that was created. 329 330 ### Creating a serverless index 331 332 ```python 333 import os 334 import asyncio 335 336 from pinecone import ( 337 PineconeAsyncio, 338 ServerlessSpec, 339 CloudProvider, 340 AwsRegion, 341 Metric, 342 DeletionProtection, 343 VectorType 344 ) 345 346 async def main(): 347 async with PineconeAsyncio(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 348 await pc.create_index( 349 name="my_index", 350 dimension=1536, 351 metric=Metric.COSINE, 352 spec=ServerlessSpec( 353 cloud=CloudProvider.AWS, 354 region=AwsRegion.US_WEST_2 355 ), 356 deletion_protection=DeletionProtection.DISABLED, 357 vector_type=VectorType.DENSE, 358 tags={ 359 "model": "clip", 360 "app": "image-search", 361 "env": "testing" 362 } 363 ) 364 365 asyncio.run(main()) 366 ``` 367 368 ### Creating a pod index 369 370 ```python 371 import os 372 import asyncio 373 374 from pinecone import ( 375 Pinecone, 376 PodSpec, 377 PodIndexEnvironment, 378 PodType, 379 Metric, 380 DeletionProtection, 381 VectorType 382 ) 383 384 async def main(): 385 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 386 await pc.create_index( 387 name="my_index", 388 dimension=1536, 389 metric=Metric.COSINE, 390 spec=PodSpec( 391 environment=PodIndexEnvironment.US_EAST4_GCP, 392 pod_type=PodType.P1_X1 393 ), 394 deletion_protection=DeletionProtection.DISABLED, 395 tags={ 396 "model": "clip", 397 "app": "image-search", 398 "env": "testing" 399 } 400 ) 401 402 asyncio.run(main()) 403 ``` 404 """ 405 pass 406 407 @abstractmethod 408 async def create_index_for_model( 409 self, 410 name: str, 411 cloud: Union[CloudProvider, str], 412 region: Union[AwsRegion, GcpRegion, AzureRegion, str], 413 embed: Union[IndexEmbed, CreateIndexForModelEmbedTypedDict], 414 tags: Optional[Dict[str, str]] = None, 415 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 416 timeout: Optional[int] = None, 417 ) -> IndexModel: 418 """ 419 :param name: The name of the index to create. Must be unique within your project and 420 cannot be changed once created. Allowed characters are lowercase letters, numbers, 421 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 422 :type name: str 423 :param cloud: The cloud provider to use for the index. One of `{"aws", "gcp", "azure"}`. 424 :type cloud: str 425 :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. 426 :type region: str 427 :param embed: The embedding configuration for the index. This param accepts a dictionary or an instance of the `IndexEmbed` object. 428 :type embed: Union[Dict, IndexEmbed] 429 :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. 430 :type tags: Optional[Dict[str, str]] 431 :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`. 432 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 433 :type timeout: Optional[int] 434 :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; 435 if -1, return immediately and do not wait. 436 :return: A description of the index that was created. 437 :rtype: IndexModel 438 439 This method is used to create a Serverless index that is configured for use with Pinecone's integrated inference models. 440 441 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. 442 443 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. 444 445 ```python 446 import asyncio 447 448 from pinecone import ( 449 PineconeAsyncio, 450 IndexEmbed, 451 CloudProvider, 452 AwsRegion, 453 EmbedModel, 454 Metric, 455 ) 456 457 async def main(): 458 async with PineconeAsyncio() as pc: 459 if not await pc.has_index("book-search"): 460 desc = await pc.create_index_for_model( 461 name="book-search", 462 cloud=CloudProvider.AWS, 463 region=AwsRegion.US_EAST_1, 464 embed=IndexEmbed( 465 model=EmbedModel.Multilingual_E5_Large, 466 metric=Metric.COSINE, 467 field_map={ 468 "text": "description", 469 }, 470 ) 471 ) 472 473 asyncio.run(main()) 474 ``` 475 476 To see the available cloud regions, see this [Pinecone documentation](https://docs.pinecone.io/troubleshooting/available-cloud-regions) page. 477 478 See the [Model Gallery](https://docs.pinecone.io/models/overview) to learn about available models. 479 """ 480 pass 481 482 @abstractmethod 483 async def delete_index(self, name: str, timeout: Optional[int] = None): 484 """ 485 :param name: the name of the index. 486 :type name: str 487 :param timeout: Number of seconds to poll status checking whether the index has been deleted. If None, 488 wait indefinitely; if >=0, time out after this many seconds; 489 if -1, return immediately and do not wait. 490 :type timeout: int, optional 491 492 Deletes a Pinecone index. 493 494 Deleting an index is an irreversible operation. All data in the index will be lost. 495 When you use this command, a request is sent to the Pinecone control plane to delete 496 the index, but the termination is not synchronous because resources take a few moments to 497 be released. 498 499 By default the `delete_index` method will block until polling of the `describe_index` method 500 shows that the delete operation has completed. If you prefer to return immediately and not 501 wait for the index to be deleted, you can pass `timeout=-1` to the method. 502 503 After the delete request is submitted, polling `describe_index` will show that the index 504 transitions into a `Terminating` state before eventually resulting in a 404 after it has been removed. 505 506 This operation can fail if the index is configured with `deletion_protection="enabled"`. 507 In this case, you will need to call `configure_index` to disable deletion protection before 508 you can delete the index. 509 510 ```python 511 import asyncio 512 513 from pinecone import PineconeAsyncio 514 515 async def main(): 516 pc = PineconeAsyncio() 517 518 index_name = "my_index" 519 desc = await pc.describe_index(name=index_name) 520 521 if desc.deletion_protection == "enabled": 522 # If for some reason deletion protection is enabled, you will need to disable it first 523 # before you can delete the index. But use caution as this operation is not reversible 524 # and if somebody enabled deletion protection, they probably had a good reason. 525 await pc.configure_index(name=index_name, deletion_protection="disabled") 526 527 await pc.delete_index(name=index_name) 528 await pc.close() 529 530 asyncio.run(main()) 531 ``` 532 """ 533 pass 534 535 @abstractmethod 536 async def list_indexes(self) -> IndexList: 537 """ 538 :return: Returns an `IndexList` object, which is iterable and contains a 539 list of `IndexModel` objects. The `IndexList` also has a convenience method `names()` 540 which returns a list of index names for situations where you just want to iterate over 541 all index names. 542 543 Lists all indexes in your project. 544 545 The results include a description of all indexes in your project, including the 546 index name, dimension, metric, status, and spec. 547 548 If you simply want to check whether an index exists, see the `has_index()` convenience method. 549 550 You can use the `list_indexes()` method to iterate over descriptions of every index in your project. 551 552 ```python 553 import asyncio 554 555 from pinecone import PineconeAsyncio 556 557 async def main(): 558 pc = PineconeAsyncio() 559 560 available_indexes = await pc.list_indexes() 561 for index in available_indexes: 562 print(index.name) 563 print(index.dimension) 564 print(index.metric) 565 print(index.status) 566 print(index.host) 567 print(index.spec) 568 569 await pc.close() 570 571 asyncio.run(main()) 572 ``` 573 """ 574 pass 575 576 @abstractmethod 577 async def describe_index(self, name: str) -> IndexModel: 578 """ 579 :param name: the name of the index to describe. 580 :return: Returns an `IndexModel` object 581 which gives access to properties such as the 582 index name, dimension, metric, host url, status, 583 and spec. 584 585 Describes a Pinecone index. 586 587 ### Getting your index host url 588 589 In a real production situation, you probably want to 590 store the host url in an environment variable so you 591 don't have to call describe_index and re-fetch it 592 every time you want to use the index. But this example 593 shows how to get the value from the API using describe_index. 594 595 ```python 596 import asyncio 597 from pinecone import Pinecone, PineconeAsyncio, Index 598 599 async def main(): 600 pc = PineconeAsyncio() 601 602 index_name="my_index" 603 description = await pc.describe_index(name=index_name) 604 print(description) 605 # { 606 # "name": "my_index", 607 # "metric": "cosine", 608 # "host": "my_index-dojoi3u.svc.aped-4627-b74a.pinecone.io", 609 # "spec": { 610 # "serverless": { 611 # "cloud": "aws", 612 # "region": "us-east-1" 613 # } 614 # }, 615 # "status": { 616 # "ready": true, 617 # "state": "Ready" 618 # }, 619 # "vector_type": "dense", 620 # "dimension": 1024, 621 # "deletion_protection": "enabled", 622 # "tags": { 623 # "environment": "production" 624 # } 625 # } 626 627 print(f"Your index is hosted at {description.host}") 628 await pc.close() 629 630 async with Pinecone().IndexAsyncio(host=description.host) as idx: 631 await idx.upsert(vectors=[...]) 632 633 asyncio.run(main()) 634 ``` 635 """ 636 pass 637 638 @abstractmethod 639 async def has_index(self, name: str) -> bool: 640 """ 641 :param name: The name of the index to check for existence. 642 :return: Returns `True` if the index exists, `False` otherwise. 643 644 Checks if a Pinecone index exists. 645 646 ```python 647 import asyncio 648 from pinecone import PineconeAsyncio, ServerlessSpec 649 650 async def main(): 651 async with PineconeAsyncio() as pc: 652 index_name = "my_index" 653 if not await pc.has_index(index_name): 654 print("Index does not exist, creating...") 655 pc.create_index( 656 name=index_name, 657 dimension=768, 658 metric="cosine", 659 spec=ServerlessSpec(cloud="aws", region="us-west-2") 660 ) 661 662 asyncio.run(main()) 663 ``` 664 """ 665 pass 666 667 @abstractmethod 668 async def configure_index( 669 self, 670 name: str, 671 replicas: Optional[int] = None, 672 pod_type: Optional[Union[PodType, str]] = None, 673 deletion_protection: Optional[Union[DeletionProtection, str]] = None, 674 tags: Optional[Dict[str, str]] = None, 675 ): 676 """ 677 :param: name: the name of the Index 678 :param: replicas: the desired number of replicas, lowest value is 0. 679 :param: pod_type: the new pod_type for the index. To learn more about the 680 available pod types, please see [Understanding Indexes](https://docs.pinecone.io/docs/indexes) 681 :param: deletion_protection: If set to 'enabled', the index cannot be deleted. If 'disabled', the index can be deleted. 682 :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. 683 684 This method is used to modify an index's configuration. It can be used to: 685 686 - Scale a pod-based index horizontally using `replicas` 687 - Scale a pod-based index vertically using `pod_type` 688 - Enable or disable deletion protection using `deletion_protection` 689 - Add, change, or remove tags using `tags` 690 691 ## Scaling pod-based indexes 692 693 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. 694 695 ```python 696 import asyncio 697 from pinecone import PineconeAsyncio, PodType 698 699 async def main(): 700 async with PineconeAsyncio() as pc: 701 await pc.configure_index( 702 name="my_index", 703 replicas=2, 704 pod_type=PodType.P1_X2 705 ) 706 707 asyncio.run(main()) 708 ``` 709 710 After providing these new configurations, you must call `describe_index` to see the status of the index as the changes are applied. 711 712 ## Enabling or disabling deletion protection 713 714 To enable or disable deletion protection, pass the `deletion_protection` parameter to the `configure_index` method. When deletion protection 715 is enabled, the index cannot be deleted with the `delete_index` method. 716 717 ```python 718 import asyncio 719 from pinecone import PineconeAsyncio, DeletionProtection 720 721 async def main(): 722 async with PineconeAsyncio() as pc: 723 # Enable deletion protection 724 await pc.configure_index( 725 name="my_index", 726 deletion_protection=DeletionProtection.ENABLED 727 ) 728 729 # Call describe_index to see the change was applied. 730 desc = await pc.describe_index("my_index") 731 assert desc.deletion_protection == "enabled" 732 733 # Disable deletion protection 734 await pc.configure_index( 735 name="my_index", 736 deletion_protection=DeletionProtection.DISABLED 737 ) 738 739 asyncio.run(main()) 740 ``` 741 742 ## Adding, changing, or removing tags 743 744 To add, change, or remove tags, pass the `tags` parameter to the `configure_index` method. When tags are passed using `configure_index`, 745 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. 746 747 ```python 748 import asyncio 749 750 from pinecone import PineconeAsyncio 751 752 async def main(): 753 async with PineconeAsyncio() as pc: 754 # Add a tag 755 await pc.configure_index(name="my_index", tags={"environment": "staging"}) 756 757 # Change a tag 758 await pc.configure_index(name="my_index", tags={"environment": "production"}) 759 760 # Remove a tag 761 await pc.configure_index(name="my_index", tags={"environment": ""}) 762 763 # Call describe_index to view the tags are changed 764 await pc.describe_index("my_index") 765 print(desc.tags) 766 767 asyncio.run(main()) 768 ``` 769 """ 770 pass 771 772 @abstractmethod 773 async def create_collection(self, name: str, source: str): 774 """Create a collection from a pod-based index 775 776 :param name: Name of the collection 777 :param source: Name of the source index 778 """ 779 pass 780 781 @abstractmethod 782 async def list_collections(self) -> CollectionList: 783 """List all collections 784 785 ```python 786 import asyncio 787 from pinecone import PineconeAsyncio 788 789 async def main(): 790 pc = PineconeAsyncio() 791 792 collections = await pc.list_collections() 793 for collection in collections: 794 print(collection.name) 795 print(collection.source) 796 797 # You can also iterate specifically over 798 # a list of collection names by calling 799 # the .names() helper. 800 collection_name = "my_collection" 801 collections = await pc.list_collections() 802 if collection_name in collections.names(): 803 print('Collection exists') 804 805 await pc.close() 806 807 asyncio.run(main()) 808 ``` 809 """ 810 pass 811 812 @abstractmethod 813 async def delete_collection(self, name: str): 814 """Describes a collection. 815 :param: The name of the collection 816 :return: Description of the collection 817 818 ```python 819 import asyncio 820 from pinecone import PineconeAsyncio 821 822 async def main(): 823 async with PineconeAsyncio() as pc: 824 825 description = await pc.describe_collection("my_collection") 826 print(description.name) 827 print(description.source) 828 print(description.status) 829 print(description.size) 830 831 asyncio.run(main()) 832 ``` 833 """ 834 pass 835 836 @abstractmethod 837 async def describe_collection(self, name: str): 838 """Describes a collection. 839 :param: The name of the collection 840 :return: Description of the collection 841 842 ```python 843 import asyncio 844 from pinecone import PineconeAsyncio 845 846 847 async def main(): 848 async with PineconeAsyncio() as pc: 849 description = await pc.describe_collection("my_collection") 850 print(description.name) 851 print(description.source) 852 print(description.status) 853 print(description.size) 854 855 asyncio.run(main()) 856 ``` 857 """ 858 pass 859 860 @abstractmethod 861 def IndexAsyncio(self, host, **kwargs): 862 """ 863 Build an asyncio-compatible client for index data operations. 864 865 :param host: The host url of the index. 866 867 ```python 868 import os 869 import asyncio 870 871 from pinecone import PineconeAsyncio 872 873 api_key = os.environ.get("PINECONE_API_KEY") 874 index_host = os.environ.get("PINECONE_INDEX_HOST") 875 876 async def main(): 877 async with Pinecone(api_key=api_key) as pc: 878 async with pc.Index(host=index_host) as idx: 879 # Now you're ready to perform data operations 880 await index.query(vector=[...], top_k=10) 881 882 asyncio.run(main()) 883 ``` 884 885 To find your host url, you can use the `describe_index`. Or, alternatively, the 886 host is displayed in the Pinecone web console. 887 888 ```python 889 import os 890 import asyncio 891 892 from pinecone import PineconeAsyncio 893 894 async def main(): 895 async with PineconeAsyncio( 896 api_key=os.environ.get("PINECONE_API_KEY") 897 ) as pc: 898 host = await pc.describe_index('index-name').host 899 900 asyncio.run(main()) 901 ``` 902 903 ## Alternative setup 904 905 Like instances of the `PineconeAsyncio` class, instances of `IndexAsyncio` have async context that 906 needs to be cleaned up when you are done with it in order to avoid error messages about unclosed session from 907 aiohttp. Nesting these in code is a bit cumbersome, so if you are only planning to do data operations you 908 may prefer to setup the `IndexAsyncio` object via the `Pinecone` class which will avoid creating an outer async context. 909 910 ```python 911 import os 912 import asyncio 913 from pinecone import Pinecone 914 915 api_key = os.environ.get("PINECONE_API_KEY") 916 917 async def main(): 918 pc = Pinecone(api_key=api_key) # sync client, so no async context to worry about 919 920 async with pc.AsyncioIndex(host='your_index_host') as idx: 921 # Now you're ready to perform data operations 922 await idx.query(vector=[...], top_k=10) 923 924 ``` 925 """ 926 pass
class
PineconeAsyncioDBControlInterface(abc.ABC):
33class PineconeAsyncioDBControlInterface(ABC): 34 @abstractmethod 35 def __init__( 36 self, 37 api_key: Optional[str] = None, 38 host: Optional[str] = None, 39 proxy_url: Optional[str] = None, 40 proxy_headers: Optional[Dict[str, str]] = None, 41 ssl_ca_certs: Optional[str] = None, 42 ssl_verify: Optional[bool] = None, 43 config: Optional[Config] = None, 44 additional_headers: Optional[Dict[str, str]] = {}, 45 pool_threads: Optional[int] = 1, 46 index_api: Optional[ManageIndexesApi] = None, 47 **kwargs, 48 ): 49 """ 50 The `PineconeAsyncio` class is the main entry point for interacting with Pinecone using asyncio. 51 It is used to create, delete, and manage your indexes and collections. Except for needing to use 52 `async with` when instantiating the client and `await` when calling its methods, the functionality 53 provided by this class is extremely similar to the functionality of the `Pinecone` class. 54 55 :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`. 56 :type api_key: str, optional 57 :param host: The control plane host to connect to. 58 :type host: str, optional 59 :param proxy_url: The URL of the proxy to use for the connection. Default: `None` 60 :type proxy_url: str, optional 61 :param proxy_headers: Additional headers to pass to the proxy. Use this if your proxy setup requires authentication. Default: `{}` 62 :type proxy_headers: Dict[str, str], optional 63 :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. Default: `None` 64 :type ssl_ca_certs: str, optional 65 :param ssl_verify: SSL verification is performed by default, but can be disabled using the boolean flag. Default: `True` 66 :type ssl_verify: bool, optional 67 :param config: A `pinecone.config.Config` object. If passed, the `api_key` and `host` parameters will be ignored. 68 :type config: pinecone.config.Config, optional 69 :param additional_headers: Additional headers to pass to the API. Default: `{}` 70 :type additional_headers: Dict[str, str], optional 71 72 73 ### Managing the async context 74 75 The `PineconeAsyncio` class relies on an underlying `aiohttp` `ClientSession` to make asynchronous HTTP requests. To ensure that the session is properly closed, you 76 should use the `async with` syntax when creating a `PineconeAsyncio` object. This will ensure that the session is properly closed when the context is exited. 77 78 ```python 79 import asyncio 80 from pinecone import PineconeAsyncio 81 82 async def main(): 83 async with PineconeAsyncio(api_key='YOUR_API_KEY') as pc: 84 # Do async things 85 index_list = await pc.list_indexes() 86 87 asyncio.run(main()) 88 ``` 89 90 As an alternative, if you prefer to avoid code with a nested appearance and are willing to manage cleanup yourself, you can await the `close()` method to close the session when you are done. 91 92 ```python 93 import asyncio 94 from pinecone import PineconeAsyncio 95 96 async def main(): 97 pc = PineconeAsyncio(api_key='YOUR_API_KEY') 98 99 # Do async things 100 index_list = await pc.list_indexes() 101 102 # You're responsible for calling this yourself 103 await pc.close() 104 105 asyncio.run(main()) 106 ``` 107 108 Failing to do this may result in error messages appearing from the underlyling aiohttp library. 109 110 ### Configuration with environment variables 111 112 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 113 114 ```python 115 import asyncio 116 from pinecone import PineconeAsyncio 117 118 async def main(): 119 async with PineconeAsyncio() as pc: 120 # Do async things 121 index_list = await pc.list_indexes() 122 123 asyncio.run(main()) 124 ``` 125 126 ### Configuration with keyword arguments 127 128 If you prefer being more explicit in your code, you can also pass the API as 129 130 ### Configuration with environment variables 131 132 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 133 134 ```python 135 import asyncio 136 from pinecone import PineconeAsyncio 137 138 async def main(): 139 async with PineconeAsyncio() as pc: 140 # Do async things 141 index_list = await pc.list_indexes() 142 143 asyncio.run(main()) 144 ``` 145 146 ### Configuration with keyword arguments 147 148 If you prefer being more explicit in your code, you can also pass the API as 149 150 151 152 ### Configuration with environment variables 153 154 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 155 156 ```python 157 import asyncio 158 from pinecone import PineconeAsyncio 159 160 async def main(): 161 async with PineconeAsyncio() as pc: 162 # Do async things 163 index_list = await pc.list_indexes() 164 165 asyncio.run(main()) 166 ``` 167 168 ### Configuration with keyword arguments 169 170 If you prefer being more explicit in your code, you can also pass the API as a keyword argument. 171 172 ```python 173 import os 174 import asyncio 175 from pinecone import PineconeAsyncio 176 177 async def main(): 178 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 179 # Do async things 180 index_list = await pc.list_indexes() 181 182 asyncio.run(main()) 183 ``` 184 185 ### Environment variables 186 187 The Pinecone client supports the following environment variables: 188 189 - `PINECONE_API_KEY`: The API key to use for authentication. If not passed via 190 kwarg, the API key will be read from the environment variable `PINECONE_API_KEY`. 191 192 ### Proxy configuration 193 194 If your network setup requires you to interact with Pinecone via a proxy, you will need 195 to pass additional configuration using optional keyword parameters. These optional parameters 196 are used to configure an SSL context and passed to `aiohttp`, which is the underlying library 197 currently used by the PineconeAsyncio client to make HTTP requests. 198 199 Here is a basic example: 200 201 ```python 202 import asyncio 203 from pinecone import PineconeAsyncio 204 205 async def main(): 206 async with PineconeAsyncio( 207 api_key='YOUR_API_KEY', 208 proxy_url='https://your-proxy.com' 209 ) as pc: 210 # Do async things 211 index_list = await pc.list_indexes() 212 213 asyncio.run(main()) 214 ``` 215 216 ### Using proxies with self-signed certificates 217 218 By default the Pinecone Python client will perform SSL certificate verification 219 using the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/certifi/) package. 220 If your proxy server is using a self-signed certificate, you will need to pass the path to the certificate 221 in PEM format using the `ssl_ca_certs` parameter. 222 223 ```python 224 import asyncio 225 from pinecone import PineconeAsyncio 226 227 async def main(): 228 async with PineconeAsyncio( 229 api_key='YOUR_API_KEY', 230 proxy_url='https://your-proxy.com', 231 ssl_ca_certs='path/to/cert-bundle.pem' 232 ) as pc: 233 # Do async things 234 await pc.list_indexes() 235 236 asyncio.run(main()) 237 ``` 238 239 ### Disabling SSL verification 240 241 If you would like to disable SSL verification, you can pass the `ssl_verify` 242 parameter with a value of `False`. We do not recommend going to production with SSL verification disabled 243 but there are situations where this is useful such as testing with Pinecone Local running in a docker 244 container. 245 246 ```python 247 import asyncio 248 from pinecone import PineconeAsyncio 249 250 async def main(): 251 async with PineconeAsyncio( 252 api_key='YOUR_API_KEY', 253 ssl_verify=False 254 ) as pc: 255 if not await pc.has_index('my_index'): 256 await pc.create_index( 257 name='my_index', 258 dimension=1536, 259 metric='cosine', 260 spec=ServerlessSpec(cloud='aws', region='us-west-2') 261 ) 262 263 asyncio.run(main()) 264 ``` 265 266 ### Passing additional headers 267 268 If you need to pass additional headers with each request to the Pinecone API, you can do so using the 269 `additional_headers` parameter. This is primarily for internal testing and end-users shouldn't need to 270 do this unless specifically instructed to do so. 271 272 ```python 273 import asyncio 274 from pinecone import PineconeAsyncio 275 276 async def main(): 277 async with PineconeAsyncio( 278 api_key='YOUR_API_KEY', 279 host='https://api-staging.pinecone.io', 280 additional_headers={'X-My-Header': 'my-value'} 281 ) as pc: 282 # Do async things 283 await pc.list_indexes() 284 285 asyncio.run(main()) 286 ``` 287 """ 288 289 pass 290 291 @abstractmethod 292 async def create_index( 293 self, 294 name: str, 295 spec: Union[Dict, ServerlessSpec, PodSpec], 296 dimension: Optional[int], 297 metric: Optional[Union[Metric, str]] = Metric.COSINE, 298 timeout: Optional[int] = None, 299 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 300 vector_type: Optional[Union[VectorType, str]] = VectorType.DENSE, 301 tags: Optional[Dict[str, str]] = None, 302 ): 303 """Creates a Pinecone index. 304 305 :param name: The name of the index to create. Must be unique within your project and 306 cannot be changed once created. Allowed characters are lowercase letters, numbers, 307 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 308 :type name: str 309 :param metric: Type of similarity metric used in the vector index when querying, one of `{"cosine", "dotproduct", "euclidean"}`. 310 :type metric: str, optional 311 :param spec: A dictionary containing configurations describing how the index should be deployed. For serverless indexes, 312 specify region and cloud. For pod indexes, specify replicas, shards, pods, pod_type, metadata_config, and source_collection. 313 Alternatively, use the `ServerlessSpec` or `PodSpec` objects to specify these configurations. 314 :type spec: Dict 315 :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. 316 This should match the dimension of the embeddings you will be inserting. For example, if you are using 317 OpenAI's CLIP model, you should use `dimension=1536`. Dimension is a required field when 318 creating an index with `vector_type="dense"` and should not be passed when `vector_type="sparse"`. 319 :type dimension: int 320 :type timeout: int, optional 321 :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; 322 if -1, return immediately and do not wait. 323 :param deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted. 324 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 325 :param vector_type: The type of vectors to be stored in the index. One of `{"dense", "sparse"}`. 326 :type vector_type: str, optional 327 :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. 328 :type tags: Optional[Dict[str, str]] 329 :return: A `IndexModel` instance containing a description of the index that was created. 330 331 ### Creating a serverless index 332 333 ```python 334 import os 335 import asyncio 336 337 from pinecone import ( 338 PineconeAsyncio, 339 ServerlessSpec, 340 CloudProvider, 341 AwsRegion, 342 Metric, 343 DeletionProtection, 344 VectorType 345 ) 346 347 async def main(): 348 async with PineconeAsyncio(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 349 await pc.create_index( 350 name="my_index", 351 dimension=1536, 352 metric=Metric.COSINE, 353 spec=ServerlessSpec( 354 cloud=CloudProvider.AWS, 355 region=AwsRegion.US_WEST_2 356 ), 357 deletion_protection=DeletionProtection.DISABLED, 358 vector_type=VectorType.DENSE, 359 tags={ 360 "model": "clip", 361 "app": "image-search", 362 "env": "testing" 363 } 364 ) 365 366 asyncio.run(main()) 367 ``` 368 369 ### Creating a pod index 370 371 ```python 372 import os 373 import asyncio 374 375 from pinecone import ( 376 Pinecone, 377 PodSpec, 378 PodIndexEnvironment, 379 PodType, 380 Metric, 381 DeletionProtection, 382 VectorType 383 ) 384 385 async def main(): 386 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 387 await pc.create_index( 388 name="my_index", 389 dimension=1536, 390 metric=Metric.COSINE, 391 spec=PodSpec( 392 environment=PodIndexEnvironment.US_EAST4_GCP, 393 pod_type=PodType.P1_X1 394 ), 395 deletion_protection=DeletionProtection.DISABLED, 396 tags={ 397 "model": "clip", 398 "app": "image-search", 399 "env": "testing" 400 } 401 ) 402 403 asyncio.run(main()) 404 ``` 405 """ 406 pass 407 408 @abstractmethod 409 async def create_index_for_model( 410 self, 411 name: str, 412 cloud: Union[CloudProvider, str], 413 region: Union[AwsRegion, GcpRegion, AzureRegion, str], 414 embed: Union[IndexEmbed, CreateIndexForModelEmbedTypedDict], 415 tags: Optional[Dict[str, str]] = None, 416 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 417 timeout: Optional[int] = None, 418 ) -> IndexModel: 419 """ 420 :param name: The name of the index to create. Must be unique within your project and 421 cannot be changed once created. Allowed characters are lowercase letters, numbers, 422 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 423 :type name: str 424 :param cloud: The cloud provider to use for the index. One of `{"aws", "gcp", "azure"}`. 425 :type cloud: str 426 :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. 427 :type region: str 428 :param embed: The embedding configuration for the index. This param accepts a dictionary or an instance of the `IndexEmbed` object. 429 :type embed: Union[Dict, IndexEmbed] 430 :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. 431 :type tags: Optional[Dict[str, str]] 432 :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`. 433 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 434 :type timeout: Optional[int] 435 :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; 436 if -1, return immediately and do not wait. 437 :return: A description of the index that was created. 438 :rtype: IndexModel 439 440 This method is used to create a Serverless index that is configured for use with Pinecone's integrated inference models. 441 442 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. 443 444 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. 445 446 ```python 447 import asyncio 448 449 from pinecone import ( 450 PineconeAsyncio, 451 IndexEmbed, 452 CloudProvider, 453 AwsRegion, 454 EmbedModel, 455 Metric, 456 ) 457 458 async def main(): 459 async with PineconeAsyncio() as pc: 460 if not await pc.has_index("book-search"): 461 desc = await pc.create_index_for_model( 462 name="book-search", 463 cloud=CloudProvider.AWS, 464 region=AwsRegion.US_EAST_1, 465 embed=IndexEmbed( 466 model=EmbedModel.Multilingual_E5_Large, 467 metric=Metric.COSINE, 468 field_map={ 469 "text": "description", 470 }, 471 ) 472 ) 473 474 asyncio.run(main()) 475 ``` 476 477 To see the available cloud regions, see this [Pinecone documentation](https://docs.pinecone.io/troubleshooting/available-cloud-regions) page. 478 479 See the [Model Gallery](https://docs.pinecone.io/models/overview) to learn about available models. 480 """ 481 pass 482 483 @abstractmethod 484 async def delete_index(self, name: str, timeout: Optional[int] = None): 485 """ 486 :param name: the name of the index. 487 :type name: str 488 :param timeout: Number of seconds to poll status checking whether the index has been deleted. If None, 489 wait indefinitely; if >=0, time out after this many seconds; 490 if -1, return immediately and do not wait. 491 :type timeout: int, optional 492 493 Deletes a Pinecone index. 494 495 Deleting an index is an irreversible operation. All data in the index will be lost. 496 When you use this command, a request is sent to the Pinecone control plane to delete 497 the index, but the termination is not synchronous because resources take a few moments to 498 be released. 499 500 By default the `delete_index` method will block until polling of the `describe_index` method 501 shows that the delete operation has completed. If you prefer to return immediately and not 502 wait for the index to be deleted, you can pass `timeout=-1` to the method. 503 504 After the delete request is submitted, polling `describe_index` will show that the index 505 transitions into a `Terminating` state before eventually resulting in a 404 after it has been removed. 506 507 This operation can fail if the index is configured with `deletion_protection="enabled"`. 508 In this case, you will need to call `configure_index` to disable deletion protection before 509 you can delete the index. 510 511 ```python 512 import asyncio 513 514 from pinecone import PineconeAsyncio 515 516 async def main(): 517 pc = PineconeAsyncio() 518 519 index_name = "my_index" 520 desc = await pc.describe_index(name=index_name) 521 522 if desc.deletion_protection == "enabled": 523 # If for some reason deletion protection is enabled, you will need to disable it first 524 # before you can delete the index. But use caution as this operation is not reversible 525 # and if somebody enabled deletion protection, they probably had a good reason. 526 await pc.configure_index(name=index_name, deletion_protection="disabled") 527 528 await pc.delete_index(name=index_name) 529 await pc.close() 530 531 asyncio.run(main()) 532 ``` 533 """ 534 pass 535 536 @abstractmethod 537 async def list_indexes(self) -> IndexList: 538 """ 539 :return: Returns an `IndexList` object, which is iterable and contains a 540 list of `IndexModel` objects. The `IndexList` also has a convenience method `names()` 541 which returns a list of index names for situations where you just want to iterate over 542 all index names. 543 544 Lists all indexes in your project. 545 546 The results include a description of all indexes in your project, including the 547 index name, dimension, metric, status, and spec. 548 549 If you simply want to check whether an index exists, see the `has_index()` convenience method. 550 551 You can use the `list_indexes()` method to iterate over descriptions of every index in your project. 552 553 ```python 554 import asyncio 555 556 from pinecone import PineconeAsyncio 557 558 async def main(): 559 pc = PineconeAsyncio() 560 561 available_indexes = await pc.list_indexes() 562 for index in available_indexes: 563 print(index.name) 564 print(index.dimension) 565 print(index.metric) 566 print(index.status) 567 print(index.host) 568 print(index.spec) 569 570 await pc.close() 571 572 asyncio.run(main()) 573 ``` 574 """ 575 pass 576 577 @abstractmethod 578 async def describe_index(self, name: str) -> IndexModel: 579 """ 580 :param name: the name of the index to describe. 581 :return: Returns an `IndexModel` object 582 which gives access to properties such as the 583 index name, dimension, metric, host url, status, 584 and spec. 585 586 Describes a Pinecone index. 587 588 ### Getting your index host url 589 590 In a real production situation, you probably want to 591 store the host url in an environment variable so you 592 don't have to call describe_index and re-fetch it 593 every time you want to use the index. But this example 594 shows how to get the value from the API using describe_index. 595 596 ```python 597 import asyncio 598 from pinecone import Pinecone, PineconeAsyncio, Index 599 600 async def main(): 601 pc = PineconeAsyncio() 602 603 index_name="my_index" 604 description = await pc.describe_index(name=index_name) 605 print(description) 606 # { 607 # "name": "my_index", 608 # "metric": "cosine", 609 # "host": "my_index-dojoi3u.svc.aped-4627-b74a.pinecone.io", 610 # "spec": { 611 # "serverless": { 612 # "cloud": "aws", 613 # "region": "us-east-1" 614 # } 615 # }, 616 # "status": { 617 # "ready": true, 618 # "state": "Ready" 619 # }, 620 # "vector_type": "dense", 621 # "dimension": 1024, 622 # "deletion_protection": "enabled", 623 # "tags": { 624 # "environment": "production" 625 # } 626 # } 627 628 print(f"Your index is hosted at {description.host}") 629 await pc.close() 630 631 async with Pinecone().IndexAsyncio(host=description.host) as idx: 632 await idx.upsert(vectors=[...]) 633 634 asyncio.run(main()) 635 ``` 636 """ 637 pass 638 639 @abstractmethod 640 async def has_index(self, name: str) -> bool: 641 """ 642 :param name: The name of the index to check for existence. 643 :return: Returns `True` if the index exists, `False` otherwise. 644 645 Checks if a Pinecone index exists. 646 647 ```python 648 import asyncio 649 from pinecone import PineconeAsyncio, ServerlessSpec 650 651 async def main(): 652 async with PineconeAsyncio() as pc: 653 index_name = "my_index" 654 if not await pc.has_index(index_name): 655 print("Index does not exist, creating...") 656 pc.create_index( 657 name=index_name, 658 dimension=768, 659 metric="cosine", 660 spec=ServerlessSpec(cloud="aws", region="us-west-2") 661 ) 662 663 asyncio.run(main()) 664 ``` 665 """ 666 pass 667 668 @abstractmethod 669 async def configure_index( 670 self, 671 name: str, 672 replicas: Optional[int] = None, 673 pod_type: Optional[Union[PodType, str]] = None, 674 deletion_protection: Optional[Union[DeletionProtection, str]] = None, 675 tags: Optional[Dict[str, str]] = None, 676 ): 677 """ 678 :param: name: the name of the Index 679 :param: replicas: the desired number of replicas, lowest value is 0. 680 :param: pod_type: the new pod_type for the index. To learn more about the 681 available pod types, please see [Understanding Indexes](https://docs.pinecone.io/docs/indexes) 682 :param: deletion_protection: If set to 'enabled', the index cannot be deleted. If 'disabled', the index can be deleted. 683 :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. 684 685 This method is used to modify an index's configuration. It can be used to: 686 687 - Scale a pod-based index horizontally using `replicas` 688 - Scale a pod-based index vertically using `pod_type` 689 - Enable or disable deletion protection using `deletion_protection` 690 - Add, change, or remove tags using `tags` 691 692 ## Scaling pod-based indexes 693 694 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. 695 696 ```python 697 import asyncio 698 from pinecone import PineconeAsyncio, PodType 699 700 async def main(): 701 async with PineconeAsyncio() as pc: 702 await pc.configure_index( 703 name="my_index", 704 replicas=2, 705 pod_type=PodType.P1_X2 706 ) 707 708 asyncio.run(main()) 709 ``` 710 711 After providing these new configurations, you must call `describe_index` to see the status of the index as the changes are applied. 712 713 ## Enabling or disabling deletion protection 714 715 To enable or disable deletion protection, pass the `deletion_protection` parameter to the `configure_index` method. When deletion protection 716 is enabled, the index cannot be deleted with the `delete_index` method. 717 718 ```python 719 import asyncio 720 from pinecone import PineconeAsyncio, DeletionProtection 721 722 async def main(): 723 async with PineconeAsyncio() as pc: 724 # Enable deletion protection 725 await pc.configure_index( 726 name="my_index", 727 deletion_protection=DeletionProtection.ENABLED 728 ) 729 730 # Call describe_index to see the change was applied. 731 desc = await pc.describe_index("my_index") 732 assert desc.deletion_protection == "enabled" 733 734 # Disable deletion protection 735 await pc.configure_index( 736 name="my_index", 737 deletion_protection=DeletionProtection.DISABLED 738 ) 739 740 asyncio.run(main()) 741 ``` 742 743 ## Adding, changing, or removing tags 744 745 To add, change, or remove tags, pass the `tags` parameter to the `configure_index` method. When tags are passed using `configure_index`, 746 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. 747 748 ```python 749 import asyncio 750 751 from pinecone import PineconeAsyncio 752 753 async def main(): 754 async with PineconeAsyncio() as pc: 755 # Add a tag 756 await pc.configure_index(name="my_index", tags={"environment": "staging"}) 757 758 # Change a tag 759 await pc.configure_index(name="my_index", tags={"environment": "production"}) 760 761 # Remove a tag 762 await pc.configure_index(name="my_index", tags={"environment": ""}) 763 764 # Call describe_index to view the tags are changed 765 await pc.describe_index("my_index") 766 print(desc.tags) 767 768 asyncio.run(main()) 769 ``` 770 """ 771 pass 772 773 @abstractmethod 774 async def create_collection(self, name: str, source: str): 775 """Create a collection from a pod-based index 776 777 :param name: Name of the collection 778 :param source: Name of the source index 779 """ 780 pass 781 782 @abstractmethod 783 async def list_collections(self) -> CollectionList: 784 """List all collections 785 786 ```python 787 import asyncio 788 from pinecone import PineconeAsyncio 789 790 async def main(): 791 pc = PineconeAsyncio() 792 793 collections = await pc.list_collections() 794 for collection in collections: 795 print(collection.name) 796 print(collection.source) 797 798 # You can also iterate specifically over 799 # a list of collection names by calling 800 # the .names() helper. 801 collection_name = "my_collection" 802 collections = await pc.list_collections() 803 if collection_name in collections.names(): 804 print('Collection exists') 805 806 await pc.close() 807 808 asyncio.run(main()) 809 ``` 810 """ 811 pass 812 813 @abstractmethod 814 async def delete_collection(self, name: str): 815 """Describes a collection. 816 :param: The name of the collection 817 :return: Description of the collection 818 819 ```python 820 import asyncio 821 from pinecone import PineconeAsyncio 822 823 async def main(): 824 async with PineconeAsyncio() as pc: 825 826 description = await pc.describe_collection("my_collection") 827 print(description.name) 828 print(description.source) 829 print(description.status) 830 print(description.size) 831 832 asyncio.run(main()) 833 ``` 834 """ 835 pass 836 837 @abstractmethod 838 async def describe_collection(self, name: str): 839 """Describes a collection. 840 :param: The name of the collection 841 :return: Description of the collection 842 843 ```python 844 import asyncio 845 from pinecone import PineconeAsyncio 846 847 848 async def main(): 849 async with PineconeAsyncio() as pc: 850 description = await pc.describe_collection("my_collection") 851 print(description.name) 852 print(description.source) 853 print(description.status) 854 print(description.size) 855 856 asyncio.run(main()) 857 ``` 858 """ 859 pass 860 861 @abstractmethod 862 def IndexAsyncio(self, host, **kwargs): 863 """ 864 Build an asyncio-compatible client for index data operations. 865 866 :param host: The host url of the index. 867 868 ```python 869 import os 870 import asyncio 871 872 from pinecone import PineconeAsyncio 873 874 api_key = os.environ.get("PINECONE_API_KEY") 875 index_host = os.environ.get("PINECONE_INDEX_HOST") 876 877 async def main(): 878 async with Pinecone(api_key=api_key) as pc: 879 async with pc.Index(host=index_host) as idx: 880 # Now you're ready to perform data operations 881 await index.query(vector=[...], top_k=10) 882 883 asyncio.run(main()) 884 ``` 885 886 To find your host url, you can use the `describe_index`. Or, alternatively, the 887 host is displayed in the Pinecone web console. 888 889 ```python 890 import os 891 import asyncio 892 893 from pinecone import PineconeAsyncio 894 895 async def main(): 896 async with PineconeAsyncio( 897 api_key=os.environ.get("PINECONE_API_KEY") 898 ) as pc: 899 host = await pc.describe_index('index-name').host 900 901 asyncio.run(main()) 902 ``` 903 904 ## Alternative setup 905 906 Like instances of the `PineconeAsyncio` class, instances of `IndexAsyncio` have async context that 907 needs to be cleaned up when you are done with it in order to avoid error messages about unclosed session from 908 aiohttp. Nesting these in code is a bit cumbersome, so if you are only planning to do data operations you 909 may prefer to setup the `IndexAsyncio` object via the `Pinecone` class which will avoid creating an outer async context. 910 911 ```python 912 import os 913 import asyncio 914 from pinecone import Pinecone 915 916 api_key = os.environ.get("PINECONE_API_KEY") 917 918 async def main(): 919 pc = Pinecone(api_key=api_key) # sync client, so no async context to worry about 920 921 async with pc.AsyncioIndex(host='your_index_host') as idx: 922 # Now you're ready to perform data operations 923 await idx.query(vector=[...], top_k=10) 924 925 ``` 926 """ 927 pass
Helper class that provides a standard way to create an ABC using inheritance.
@abstractmethod
PineconeAsyncioDBControlInterface( api_key: Optional[str] = None, host: Optional[str] = None, proxy_url: Optional[str] = None, proxy_headers: Optional[Dict[str, str]] = None, ssl_ca_certs: Optional[str] = None, ssl_verify: Optional[bool] = None, config: Optional[pinecone.config.config.Config] = None, additional_headers: Optional[Dict[str, str]] = {}, pool_threads: Optional[int] = 1, index_api: Optional[pinecone.core.openapi.db_control.api.manage_indexes_api.ManageIndexesApi] = None, **kwargs)
34 @abstractmethod 35 def __init__( 36 self, 37 api_key: Optional[str] = None, 38 host: Optional[str] = None, 39 proxy_url: Optional[str] = None, 40 proxy_headers: Optional[Dict[str, str]] = None, 41 ssl_ca_certs: Optional[str] = None, 42 ssl_verify: Optional[bool] = None, 43 config: Optional[Config] = None, 44 additional_headers: Optional[Dict[str, str]] = {}, 45 pool_threads: Optional[int] = 1, 46 index_api: Optional[ManageIndexesApi] = None, 47 **kwargs, 48 ): 49 """ 50 The `PineconeAsyncio` class is the main entry point for interacting with Pinecone using asyncio. 51 It is used to create, delete, and manage your indexes and collections. Except for needing to use 52 `async with` when instantiating the client and `await` when calling its methods, the functionality 53 provided by this class is extremely similar to the functionality of the `Pinecone` class. 54 55 :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`. 56 :type api_key: str, optional 57 :param host: The control plane host to connect to. 58 :type host: str, optional 59 :param proxy_url: The URL of the proxy to use for the connection. Default: `None` 60 :type proxy_url: str, optional 61 :param proxy_headers: Additional headers to pass to the proxy. Use this if your proxy setup requires authentication. Default: `{}` 62 :type proxy_headers: Dict[str, str], optional 63 :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. Default: `None` 64 :type ssl_ca_certs: str, optional 65 :param ssl_verify: SSL verification is performed by default, but can be disabled using the boolean flag. Default: `True` 66 :type ssl_verify: bool, optional 67 :param config: A `pinecone.config.Config` object. If passed, the `api_key` and `host` parameters will be ignored. 68 :type config: pinecone.config.Config, optional 69 :param additional_headers: Additional headers to pass to the API. Default: `{}` 70 :type additional_headers: Dict[str, str], optional 71 72 73 ### Managing the async context 74 75 The `PineconeAsyncio` class relies on an underlying `aiohttp` `ClientSession` to make asynchronous HTTP requests. To ensure that the session is properly closed, you 76 should use the `async with` syntax when creating a `PineconeAsyncio` object. This will ensure that the session is properly closed when the context is exited. 77 78 ```python 79 import asyncio 80 from pinecone import PineconeAsyncio 81 82 async def main(): 83 async with PineconeAsyncio(api_key='YOUR_API_KEY') as pc: 84 # Do async things 85 index_list = await pc.list_indexes() 86 87 asyncio.run(main()) 88 ``` 89 90 As an alternative, if you prefer to avoid code with a nested appearance and are willing to manage cleanup yourself, you can await the `close()` method to close the session when you are done. 91 92 ```python 93 import asyncio 94 from pinecone import PineconeAsyncio 95 96 async def main(): 97 pc = PineconeAsyncio(api_key='YOUR_API_KEY') 98 99 # Do async things 100 index_list = await pc.list_indexes() 101 102 # You're responsible for calling this yourself 103 await pc.close() 104 105 asyncio.run(main()) 106 ``` 107 108 Failing to do this may result in error messages appearing from the underlyling aiohttp library. 109 110 ### Configuration with environment variables 111 112 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 113 114 ```python 115 import asyncio 116 from pinecone import PineconeAsyncio 117 118 async def main(): 119 async with PineconeAsyncio() as pc: 120 # Do async things 121 index_list = await pc.list_indexes() 122 123 asyncio.run(main()) 124 ``` 125 126 ### Configuration with keyword arguments 127 128 If you prefer being more explicit in your code, you can also pass the API as 129 130 ### Configuration with environment variables 131 132 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 133 134 ```python 135 import asyncio 136 from pinecone import PineconeAsyncio 137 138 async def main(): 139 async with PineconeAsyncio() as pc: 140 # Do async things 141 index_list = await pc.list_indexes() 142 143 asyncio.run(main()) 144 ``` 145 146 ### Configuration with keyword arguments 147 148 If you prefer being more explicit in your code, you can also pass the API as 149 150 151 152 ### Configuration with environment variables 153 154 If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable `PINECONE_API_KEY`. 155 156 ```python 157 import asyncio 158 from pinecone import PineconeAsyncio 159 160 async def main(): 161 async with PineconeAsyncio() as pc: 162 # Do async things 163 index_list = await pc.list_indexes() 164 165 asyncio.run(main()) 166 ``` 167 168 ### Configuration with keyword arguments 169 170 If you prefer being more explicit in your code, you can also pass the API as a keyword argument. 171 172 ```python 173 import os 174 import asyncio 175 from pinecone import PineconeAsyncio 176 177 async def main(): 178 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 179 # Do async things 180 index_list = await pc.list_indexes() 181 182 asyncio.run(main()) 183 ``` 184 185 ### Environment variables 186 187 The Pinecone client supports the following environment variables: 188 189 - `PINECONE_API_KEY`: The API key to use for authentication. If not passed via 190 kwarg, the API key will be read from the environment variable `PINECONE_API_KEY`. 191 192 ### Proxy configuration 193 194 If your network setup requires you to interact with Pinecone via a proxy, you will need 195 to pass additional configuration using optional keyword parameters. These optional parameters 196 are used to configure an SSL context and passed to `aiohttp`, which is the underlying library 197 currently used by the PineconeAsyncio client to make HTTP requests. 198 199 Here is a basic example: 200 201 ```python 202 import asyncio 203 from pinecone import PineconeAsyncio 204 205 async def main(): 206 async with PineconeAsyncio( 207 api_key='YOUR_API_KEY', 208 proxy_url='https://your-proxy.com' 209 ) as pc: 210 # Do async things 211 index_list = await pc.list_indexes() 212 213 asyncio.run(main()) 214 ``` 215 216 ### Using proxies with self-signed certificates 217 218 By default the Pinecone Python client will perform SSL certificate verification 219 using the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/certifi/) package. 220 If your proxy server is using a self-signed certificate, you will need to pass the path to the certificate 221 in PEM format using the `ssl_ca_certs` parameter. 222 223 ```python 224 import asyncio 225 from pinecone import PineconeAsyncio 226 227 async def main(): 228 async with PineconeAsyncio( 229 api_key='YOUR_API_KEY', 230 proxy_url='https://your-proxy.com', 231 ssl_ca_certs='path/to/cert-bundle.pem' 232 ) as pc: 233 # Do async things 234 await pc.list_indexes() 235 236 asyncio.run(main()) 237 ``` 238 239 ### Disabling SSL verification 240 241 If you would like to disable SSL verification, you can pass the `ssl_verify` 242 parameter with a value of `False`. We do not recommend going to production with SSL verification disabled 243 but there are situations where this is useful such as testing with Pinecone Local running in a docker 244 container. 245 246 ```python 247 import asyncio 248 from pinecone import PineconeAsyncio 249 250 async def main(): 251 async with PineconeAsyncio( 252 api_key='YOUR_API_KEY', 253 ssl_verify=False 254 ) as pc: 255 if not await pc.has_index('my_index'): 256 await pc.create_index( 257 name='my_index', 258 dimension=1536, 259 metric='cosine', 260 spec=ServerlessSpec(cloud='aws', region='us-west-2') 261 ) 262 263 asyncio.run(main()) 264 ``` 265 266 ### Passing additional headers 267 268 If you need to pass additional headers with each request to the Pinecone API, you can do so using the 269 `additional_headers` parameter. This is primarily for internal testing and end-users shouldn't need to 270 do this unless specifically instructed to do so. 271 272 ```python 273 import asyncio 274 from pinecone import PineconeAsyncio 275 276 async def main(): 277 async with PineconeAsyncio( 278 api_key='YOUR_API_KEY', 279 host='https://api-staging.pinecone.io', 280 additional_headers={'X-My-Header': 'my-value'} 281 ) as pc: 282 # Do async things 283 await pc.list_indexes() 284 285 asyncio.run(main()) 286 ``` 287 """
The PineconeAsyncio class is the main entry point for interacting with Pinecone using asyncio.
It is used to create, delete, and manage your indexes and collections. Except for needing to use
async with when instantiating the client and await when calling its methods, the functionality
provided by this class is extremely similar to the functionality of the Pinecone class.
Parameters
- 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. - host: The control plane host to connect to.
- proxy_url: The URL of the proxy to use for the connection. Default:
None - proxy_headers: Additional headers to pass to the proxy. Use this if your proxy setup requires authentication. Default:
{} - 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. Default:
None - ssl_verify: SSL verification is performed by default, but can be disabled using the boolean flag. Default:
True - config: A
pinecone.config.Configobject. If passed, theapi_keyandhostparameters will be ignored. - additional_headers: Additional headers to pass to the API. Default:
{}
Managing the async context
The PineconeAsyncio class relies on an underlying aiohttp ClientSession to make asynchronous HTTP requests. To ensure that the session is properly closed, you
should use the async with syntax when creating a PineconeAsyncio object. This will ensure that the session is properly closed when the context is exited.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(api_key='YOUR_API_KEY') as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
As an alternative, if you prefer to avoid code with a nested appearance and are willing to manage cleanup yourself, you can await the close() method to close the session when you are done.
import asyncio
from pinecone import PineconeAsyncio
async def main():
pc = PineconeAsyncio(api_key='YOUR_API_KEY')
# Do async things
index_list = await pc.list_indexes()
# You're responsible for calling this yourself
await pc.close()
asyncio.run(main())
Failing to do this may result in error messages appearing from the underlyling aiohttp library.
Configuration with environment variables
If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable PINECONE_API_KEY.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
Configuration with keyword arguments
If you prefer being more explicit in your code, you can also pass the API as
Configuration with environment variables
If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable PINECONE_API_KEY.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
Configuration with keyword arguments
If you prefer being more explicit in your code, you can also pass the API as
Configuration with environment variables
If you instantiate the Pinecone client with no arguments, it will attempt to read the API key from the environment variable PINECONE_API_KEY.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
Configuration with keyword arguments
If you prefer being more explicit in your code, you can also pass the API as a keyword argument.
import os
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
Environment variables
The Pinecone client supports the following environment variables:
PINECONE_API_KEY: The API key to use for authentication. If not passed via kwarg, the API key will be read from the environment variablePINECONE_API_KEY.
Proxy configuration
If your network setup requires you to interact with Pinecone via a proxy, you will need
to pass additional configuration using optional keyword parameters. These optional parameters
are used to configure an SSL context and passed to aiohttp, which is the underlying library
currently used by the PineconeAsyncio client to make HTTP requests.
Here is a basic example:
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(
api_key='YOUR_API_KEY',
proxy_url='https://your-proxy.com'
) as pc:
# Do async things
index_list = await pc.list_indexes()
asyncio.run(main())
Using proxies with self-signed certificates
By default the Pinecone Python client will perform SSL certificate verification
using the CA bundle maintained by Mozilla in the certifi package.
If your proxy server is using a self-signed certificate, you will need to pass the path to the certificate
in PEM format using the ssl_ca_certs parameter.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(
api_key='YOUR_API_KEY',
proxy_url='https://your-proxy.com',
ssl_ca_certs='path/to/cert-bundle.pem'
) as pc:
# Do async things
await pc.list_indexes()
asyncio.run(main())
Disabling SSL verification
If you would like to disable SSL verification, you can pass the ssl_verify
parameter with a value of False. We do not recommend going to production with SSL verification disabled
but there are situations where this is useful such as testing with Pinecone Local running in a docker
container.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(
api_key='YOUR_API_KEY',
ssl_verify=False
) as pc:
if not await pc.has_index('my_index'):
await pc.create_index(
name='my_index',
dimension=1536,
metric='cosine',
spec=ServerlessSpec(cloud='aws', region='us-west-2')
)
asyncio.run(main())
Passing additional headers
If you need to pass additional headers with each request to the Pinecone API, you can do so using the
additional_headers parameter. This is primarily for internal testing and end-users shouldn't need to
do this unless specifically instructed to do so.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(
api_key='YOUR_API_KEY',
host='https://api-staging.pinecone.io',
additional_headers={'X-My-Header': 'my-value'}
) as pc:
# Do async things
await pc.list_indexes()
asyncio.run(main())
@abstractmethod
async def
create_index( self, name: str, spec: Union[Dict, pinecone.models.serverless_spec.ServerlessSpec, pinecone.models.pod_spec.PodSpec], dimension: Optional[int], metric: Union[pinecone.enums.metric.Metric, str, NoneType] = <Metric.COSINE: 'cosine'>, timeout: Optional[int] = None, deletion_protection: Union[pinecone.enums.deletion_protection.DeletionProtection, str, NoneType] = <DeletionProtection.DISABLED: 'disabled'>, vector_type: Union[pinecone.enums.vector_type.VectorType, str, NoneType] = <VectorType.DENSE: 'dense'>, tags: Optional[Dict[str, str]] = None):
291 @abstractmethod 292 async def create_index( 293 self, 294 name: str, 295 spec: Union[Dict, ServerlessSpec, PodSpec], 296 dimension: Optional[int], 297 metric: Optional[Union[Metric, str]] = Metric.COSINE, 298 timeout: Optional[int] = None, 299 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 300 vector_type: Optional[Union[VectorType, str]] = VectorType.DENSE, 301 tags: Optional[Dict[str, str]] = None, 302 ): 303 """Creates a Pinecone index. 304 305 :param name: The name of the index to create. Must be unique within your project and 306 cannot be changed once created. Allowed characters are lowercase letters, numbers, 307 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 308 :type name: str 309 :param metric: Type of similarity metric used in the vector index when querying, one of `{"cosine", "dotproduct", "euclidean"}`. 310 :type metric: str, optional 311 :param spec: A dictionary containing configurations describing how the index should be deployed. For serverless indexes, 312 specify region and cloud. For pod indexes, specify replicas, shards, pods, pod_type, metadata_config, and source_collection. 313 Alternatively, use the `ServerlessSpec` or `PodSpec` objects to specify these configurations. 314 :type spec: Dict 315 :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. 316 This should match the dimension of the embeddings you will be inserting. For example, if you are using 317 OpenAI's CLIP model, you should use `dimension=1536`. Dimension is a required field when 318 creating an index with `vector_type="dense"` and should not be passed when `vector_type="sparse"`. 319 :type dimension: int 320 :type timeout: int, optional 321 :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; 322 if -1, return immediately and do not wait. 323 :param deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted. 324 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 325 :param vector_type: The type of vectors to be stored in the index. One of `{"dense", "sparse"}`. 326 :type vector_type: str, optional 327 :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. 328 :type tags: Optional[Dict[str, str]] 329 :return: A `IndexModel` instance containing a description of the index that was created. 330 331 ### Creating a serverless index 332 333 ```python 334 import os 335 import asyncio 336 337 from pinecone import ( 338 PineconeAsyncio, 339 ServerlessSpec, 340 CloudProvider, 341 AwsRegion, 342 Metric, 343 DeletionProtection, 344 VectorType 345 ) 346 347 async def main(): 348 async with PineconeAsyncio(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 349 await pc.create_index( 350 name="my_index", 351 dimension=1536, 352 metric=Metric.COSINE, 353 spec=ServerlessSpec( 354 cloud=CloudProvider.AWS, 355 region=AwsRegion.US_WEST_2 356 ), 357 deletion_protection=DeletionProtection.DISABLED, 358 vector_type=VectorType.DENSE, 359 tags={ 360 "model": "clip", 361 "app": "image-search", 362 "env": "testing" 363 } 364 ) 365 366 asyncio.run(main()) 367 ``` 368 369 ### Creating a pod index 370 371 ```python 372 import os 373 import asyncio 374 375 from pinecone import ( 376 Pinecone, 377 PodSpec, 378 PodIndexEnvironment, 379 PodType, 380 Metric, 381 DeletionProtection, 382 VectorType 383 ) 384 385 async def main(): 386 async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc: 387 await pc.create_index( 388 name="my_index", 389 dimension=1536, 390 metric=Metric.COSINE, 391 spec=PodSpec( 392 environment=PodIndexEnvironment.US_EAST4_GCP, 393 pod_type=PodType.P1_X1 394 ), 395 deletion_protection=DeletionProtection.DISABLED, 396 tags={ 397 "model": "clip", 398 "app": "image-search", 399 "env": "testing" 400 } 401 ) 402 403 asyncio.run(main()) 404 ``` 405 """ 406 pass
Creates a Pinecone index.
Parameters
- name: The name of the index to create. Must be unique within your project and cannot be changed once created. Allowed characters are lowercase letters, numbers, and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters.
- metric: Type of similarity metric used in the vector index when querying, one of
{"cosine", "dotproduct", "euclidean"}. - spec: A dictionary containing configurations describing how the index should be deployed. For serverless indexes,
specify region and cloud. For pod indexes, specify replicas, shards, pods, pod_type, metadata_config, and source_collection.
Alternatively, use the
ServerlessSpecorPodSpecobjects to specify these configurations. - dimension: If you are creating an index with
vector_type="dense"(which is the default), you need to specifydimensionto indicate the size of your vectors. This should match the dimension of the embeddings you will be inserting. For example, if you are using OpenAI's CLIP model, you should usedimension=1536. Dimension is a required field when creating an index withvector_type="dense"and should not be passed whenvector_type="sparse". - timeout: Specify the number of seconds to wait until index gets ready. If None, wait indefinitely; if >=0, time out after this many seconds; if -1, return immediately and do not wait.
- deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted.
- vector_type: The type of vectors to be stored in the index. One of
{"dense", "sparse"}. - 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.
Returns
A
IndexModelinstance containing a description of the index that was created.
Creating a serverless index
import os
import asyncio
from pinecone import (
PineconeAsyncio,
ServerlessSpec,
CloudProvider,
AwsRegion,
Metric,
DeletionProtection,
VectorType
)
async def main():
async with PineconeAsyncio(api_key=os.environ.get("PINECONE_API_KEY")) as pc:
await pc.create_index(
name="my_index",
dimension=1536,
metric=Metric.COSINE,
spec=ServerlessSpec(
cloud=CloudProvider.AWS,
region=AwsRegion.US_WEST_2
),
deletion_protection=DeletionProtection.DISABLED,
vector_type=VectorType.DENSE,
tags={
"model": "clip",
"app": "image-search",
"env": "testing"
}
)
asyncio.run(main())
Creating a pod index
import os
import asyncio
from pinecone import (
Pinecone,
PodSpec,
PodIndexEnvironment,
PodType,
Metric,
DeletionProtection,
VectorType
)
async def main():
async with Pinecone(api_key=os.environ.get("PINECONE_API_KEY")) as pc:
await pc.create_index(
name="my_index",
dimension=1536,
metric=Metric.COSINE,
spec=PodSpec(
environment=PodIndexEnvironment.US_EAST4_GCP,
pod_type=PodType.P1_X1
),
deletion_protection=DeletionProtection.DISABLED,
tags={
"model": "clip",
"app": "image-search",
"env": "testing"
}
)
asyncio.run(main())
@abstractmethod
async def
create_index_for_model( self, name: str, cloud: Union[pinecone.enums.clouds.CloudProvider, str], region: Union[pinecone.enums.clouds.AwsRegion, pinecone.enums.clouds.GcpRegion, pinecone.enums.clouds.AzureRegion, str], embed: Union[pinecone.models.index_embed.IndexEmbed, pinecone.control.types.create_index_for_model_embed.CreateIndexForModelEmbedTypedDict], tags: Optional[Dict[str, str]] = None, deletion_protection: Union[pinecone.enums.deletion_protection.DeletionProtection, str, NoneType] = <DeletionProtection.DISABLED: 'disabled'>, timeout: Optional[int] = None) -> pinecone.models.index_model.IndexModel:
408 @abstractmethod 409 async def create_index_for_model( 410 self, 411 name: str, 412 cloud: Union[CloudProvider, str], 413 region: Union[AwsRegion, GcpRegion, AzureRegion, str], 414 embed: Union[IndexEmbed, CreateIndexForModelEmbedTypedDict], 415 tags: Optional[Dict[str, str]] = None, 416 deletion_protection: Optional[Union[DeletionProtection, str]] = DeletionProtection.DISABLED, 417 timeout: Optional[int] = None, 418 ) -> IndexModel: 419 """ 420 :param name: The name of the index to create. Must be unique within your project and 421 cannot be changed once created. Allowed characters are lowercase letters, numbers, 422 and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters. 423 :type name: str 424 :param cloud: The cloud provider to use for the index. One of `{"aws", "gcp", "azure"}`. 425 :type cloud: str 426 :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. 427 :type region: str 428 :param embed: The embedding configuration for the index. This param accepts a dictionary or an instance of the `IndexEmbed` object. 429 :type embed: Union[Dict, IndexEmbed] 430 :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. 431 :type tags: Optional[Dict[str, str]] 432 :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`. 433 :type deletion_protection: Optional[Literal["enabled", "disabled"]] 434 :type timeout: Optional[int] 435 :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; 436 if -1, return immediately and do not wait. 437 :return: A description of the index that was created. 438 :rtype: IndexModel 439 440 This method is used to create a Serverless index that is configured for use with Pinecone's integrated inference models. 441 442 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. 443 444 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. 445 446 ```python 447 import asyncio 448 449 from pinecone import ( 450 PineconeAsyncio, 451 IndexEmbed, 452 CloudProvider, 453 AwsRegion, 454 EmbedModel, 455 Metric, 456 ) 457 458 async def main(): 459 async with PineconeAsyncio() as pc: 460 if not await pc.has_index("book-search"): 461 desc = await pc.create_index_for_model( 462 name="book-search", 463 cloud=CloudProvider.AWS, 464 region=AwsRegion.US_EAST_1, 465 embed=IndexEmbed( 466 model=EmbedModel.Multilingual_E5_Large, 467 metric=Metric.COSINE, 468 field_map={ 469 "text": "description", 470 }, 471 ) 472 ) 473 474 asyncio.run(main()) 475 ``` 476 477 To see the available cloud regions, see this [Pinecone documentation](https://docs.pinecone.io/troubleshooting/available-cloud-regions) page. 478 479 See the [Model Gallery](https://docs.pinecone.io/models/overview) to learn about available models. 480 """ 481 pass
Parameters
- name: The name of the index to create. Must be unique within your project and cannot be changed once created. Allowed characters are lowercase letters, numbers, and hyphens and the name may not begin or end with hyphens. Maximum length is 45 characters.
- cloud: The cloud provider to use for the index. One of
{"aws", "gcp", "azure"}. - region: The region to use for the index. Enum objects
AwsRegion,GcpRegion, andAzureRegionare also available to help you quickly set these parameters, but may not be up to date as new regions become available. - embed: The embedding configuration for the index. This param accepts a dictionary or an instance of the
IndexEmbedobject. - 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.
- deletion_protection: If enabled, the index cannot be deleted. If disabled, the index can be deleted. This setting can be changed with
configure_index. - 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; if -1, return immediately and do not wait.
Returns
A description of the index that was created.
This method is used to create a Serverless index that is configured for use with Pinecone's integrated inference models.
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.
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.
import asyncio
from pinecone import (
PineconeAsyncio,
IndexEmbed,
CloudProvider,
AwsRegion,
EmbedModel,
Metric,
)
async def main():
async with PineconeAsyncio() as pc:
if not await pc.has_index("book-search"):
desc = await pc.create_index_for_model(
name="book-search",
cloud=CloudProvider.AWS,
region=AwsRegion.US_EAST_1,
embed=IndexEmbed(
model=EmbedModel.Multilingual_E5_Large,
metric=Metric.COSINE,
field_map={
"text": "description",
},
)
)
asyncio.run(main())
To see the available cloud regions, see this pinecone.control.pinecone.io/troubleshooting/available-cloud-regions">Pinecone documentation page.
See the pinecone.control.pinecone.io/models/overview">Model Gallery to learn about available models.
@abstractmethod
async def
delete_index(self, name: str, timeout: Optional[int] = None):
483 @abstractmethod 484 async def delete_index(self, name: str, timeout: Optional[int] = None): 485 """ 486 :param name: the name of the index. 487 :type name: str 488 :param timeout: Number of seconds to poll status checking whether the index has been deleted. If None, 489 wait indefinitely; if >=0, time out after this many seconds; 490 if -1, return immediately and do not wait. 491 :type timeout: int, optional 492 493 Deletes a Pinecone index. 494 495 Deleting an index is an irreversible operation. All data in the index will be lost. 496 When you use this command, a request is sent to the Pinecone control plane to delete 497 the index, but the termination is not synchronous because resources take a few moments to 498 be released. 499 500 By default the `delete_index` method will block until polling of the `describe_index` method 501 shows that the delete operation has completed. If you prefer to return immediately and not 502 wait for the index to be deleted, you can pass `timeout=-1` to the method. 503 504 After the delete request is submitted, polling `describe_index` will show that the index 505 transitions into a `Terminating` state before eventually resulting in a 404 after it has been removed. 506 507 This operation can fail if the index is configured with `deletion_protection="enabled"`. 508 In this case, you will need to call `configure_index` to disable deletion protection before 509 you can delete the index. 510 511 ```python 512 import asyncio 513 514 from pinecone import PineconeAsyncio 515 516 async def main(): 517 pc = PineconeAsyncio() 518 519 index_name = "my_index" 520 desc = await pc.describe_index(name=index_name) 521 522 if desc.deletion_protection == "enabled": 523 # If for some reason deletion protection is enabled, you will need to disable it first 524 # before you can delete the index. But use caution as this operation is not reversible 525 # and if somebody enabled deletion protection, they probably had a good reason. 526 await pc.configure_index(name=index_name, deletion_protection="disabled") 527 528 await pc.delete_index(name=index_name) 529 await pc.close() 530 531 asyncio.run(main()) 532 ``` 533 """ 534 pass
Parameters
- name: the name of the index.
- timeout: Number of seconds to poll status checking whether the index has been deleted. If None, wait indefinitely; if >=0, time out after this many seconds; if -1, return immediately and do not wait.
Deletes a Pinecone index.
Deleting an index is an irreversible operation. All data in the index will be lost. When you use this command, a request is sent to the Pinecone control plane to delete the index, but the termination is not synchronous because resources take a few moments to be released.
By default the delete_index method will block until polling of the describe_index method
shows that the delete operation has completed. If you prefer to return immediately and not
wait for the index to be deleted, you can pass timeout=-1 to the method.
After the delete request is submitted, polling describe_index will show that the index
transitions into a Terminating state before eventually resulting in a 404 after it has been removed.
This operation can fail if the index is configured with deletion_protection="enabled".
In this case, you will need to call configure_index to disable deletion protection before
you can delete the index.
import asyncio
from pinecone import PineconeAsyncio
async def main():
pc = PineconeAsyncio()
index_name = "my_index"
desc = await pc.describe_index(name=index_name)
if desc.deletion_protection == "enabled":
# If for some reason deletion protection is enabled, you will need to disable it first
# before you can delete the index. But use caution as this operation is not reversible
# and if somebody enabled deletion protection, they probably had a good reason.
await pc.configure_index(name=index_name, deletion_protection="disabled")
await pc.delete_index(name=index_name)
await pc.close()
asyncio.run(main())
@abstractmethod
async def
list_indexes(self) -> pinecone.models.index_list.IndexList:
536 @abstractmethod 537 async def list_indexes(self) -> IndexList: 538 """ 539 :return: Returns an `IndexList` object, which is iterable and contains a 540 list of `IndexModel` objects. The `IndexList` also has a convenience method `names()` 541 which returns a list of index names for situations where you just want to iterate over 542 all index names. 543 544 Lists all indexes in your project. 545 546 The results include a description of all indexes in your project, including the 547 index name, dimension, metric, status, and spec. 548 549 If you simply want to check whether an index exists, see the `has_index()` convenience method. 550 551 You can use the `list_indexes()` method to iterate over descriptions of every index in your project. 552 553 ```python 554 import asyncio 555 556 from pinecone import PineconeAsyncio 557 558 async def main(): 559 pc = PineconeAsyncio() 560 561 available_indexes = await pc.list_indexes() 562 for index in available_indexes: 563 print(index.name) 564 print(index.dimension) 565 print(index.metric) 566 print(index.status) 567 print(index.host) 568 print(index.spec) 569 570 await pc.close() 571 572 asyncio.run(main()) 573 ``` 574 """ 575 pass
Returns
Returns an
IndexListobject, which is iterable and contains a list ofIndexModelobjects. TheIndexListalso has a convenience methodnames()which returns a list of index names for situations where you just want to iterate over all index names.
Lists all indexes in your project.
The results include a description of all indexes in your project, including the index name, dimension, metric, status, and spec.
If you simply want to check whether an index exists, see the has_index() convenience method.
You can use the list_indexes() method to iterate over descriptions of every index in your project.
import asyncio
from pinecone import PineconeAsyncio
async def main():
pc = PineconeAsyncio()
available_indexes = await pc.list_indexes()
for index in available_indexes:
print(index.name)
print(index.dimension)
print(index.metric)
print(index.status)
print(index.host)
print(index.spec)
await pc.close()
asyncio.run(main())
@abstractmethod
async def
describe_index(self, name: str) -> pinecone.models.index_model.IndexModel:
577 @abstractmethod 578 async def describe_index(self, name: str) -> IndexModel: 579 """ 580 :param name: the name of the index to describe. 581 :return: Returns an `IndexModel` object 582 which gives access to properties such as the 583 index name, dimension, metric, host url, status, 584 and spec. 585 586 Describes a Pinecone index. 587 588 ### Getting your index host url 589 590 In a real production situation, you probably want to 591 store the host url in an environment variable so you 592 don't have to call describe_index and re-fetch it 593 every time you want to use the index. But this example 594 shows how to get the value from the API using describe_index. 595 596 ```python 597 import asyncio 598 from pinecone import Pinecone, PineconeAsyncio, Index 599 600 async def main(): 601 pc = PineconeAsyncio() 602 603 index_name="my_index" 604 description = await pc.describe_index(name=index_name) 605 print(description) 606 # { 607 # "name": "my_index", 608 # "metric": "cosine", 609 # "host": "my_index-dojoi3u.svc.aped-4627-b74a.pinecone.io", 610 # "spec": { 611 # "serverless": { 612 # "cloud": "aws", 613 # "region": "us-east-1" 614 # } 615 # }, 616 # "status": { 617 # "ready": true, 618 # "state": "Ready" 619 # }, 620 # "vector_type": "dense", 621 # "dimension": 1024, 622 # "deletion_protection": "enabled", 623 # "tags": { 624 # "environment": "production" 625 # } 626 # } 627 628 print(f"Your index is hosted at {description.host}") 629 await pc.close() 630 631 async with Pinecone().IndexAsyncio(host=description.host) as idx: 632 await idx.upsert(vectors=[...]) 633 634 asyncio.run(main()) 635 ``` 636 """ 637 pass
Parameters
- name: the name of the index to describe.
Returns
Returns an
IndexModelobject which gives access to properties such as the index name, dimension, metric, host url, status, and spec.
Describes a Pinecone index.
Getting your index host url
In a real production situation, you probably want to store the host url in an environment variable so you don't have to call describe_index and re-fetch it every time you want to use the index. But this example shows how to get the value from the API using describe_index.
import asyncio
from pinecone import Pinecone, PineconeAsyncio, Index
async def main():
pc = PineconeAsyncio()
index_name="my_index"
description = await pc.describe_index(name=index_name)
print(description)
# {
# "name": "my_index",
# "metric": "cosine",
# "host": "my_index-dojoi3u.svc.aped-4627-b74a.pinecone.io",
# "spec": {
# "serverless": {
# "cloud": "aws",
# "region": "us-east-1"
# }
# },
# "status": {
# "ready": true,
# "state": "Ready"
# },
# "vector_type": "dense",
# "dimension": 1024,
# "deletion_protection": "enabled",
# "tags": {
# "environment": "production"
# }
# }
print(f"Your index is hosted at {description.host}")
await pc.close()
async with Pinecone().IndexAsyncio(host=description.host) as idx:
await idx.upsert(vectors=[...])
asyncio.run(main())
@abstractmethod
async def
has_index(self, name: str) -> bool:
639 @abstractmethod 640 async def has_index(self, name: str) -> bool: 641 """ 642 :param name: The name of the index to check for existence. 643 :return: Returns `True` if the index exists, `False` otherwise. 644 645 Checks if a Pinecone index exists. 646 647 ```python 648 import asyncio 649 from pinecone import PineconeAsyncio, ServerlessSpec 650 651 async def main(): 652 async with PineconeAsyncio() as pc: 653 index_name = "my_index" 654 if not await pc.has_index(index_name): 655 print("Index does not exist, creating...") 656 pc.create_index( 657 name=index_name, 658 dimension=768, 659 metric="cosine", 660 spec=ServerlessSpec(cloud="aws", region="us-west-2") 661 ) 662 663 asyncio.run(main()) 664 ``` 665 """ 666 pass
Parameters
- name: The name of the index to check for existence.
Returns
Returns
Trueif the index exists,Falseotherwise.
Checks if a Pinecone index exists.
import asyncio
from pinecone import PineconeAsyncio, ServerlessSpec
async def main():
async with PineconeAsyncio() as pc:
index_name = "my_index"
if not await pc.has_index(index_name):
print("Index does not exist, creating...")
pc.create_index(
name=index_name,
dimension=768,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-west-2")
)
asyncio.run(main())
@abstractmethod
async def
configure_index( self, name: str, replicas: Optional[int] = None, pod_type: Union[pinecone.enums.pod_type.PodType, str, NoneType] = None, deletion_protection: Union[pinecone.enums.deletion_protection.DeletionProtection, str, NoneType] = None, tags: Optional[Dict[str, str]] = None):
668 @abstractmethod 669 async def configure_index( 670 self, 671 name: str, 672 replicas: Optional[int] = None, 673 pod_type: Optional[Union[PodType, str]] = None, 674 deletion_protection: Optional[Union[DeletionProtection, str]] = None, 675 tags: Optional[Dict[str, str]] = None, 676 ): 677 """ 678 :param: name: the name of the Index 679 :param: replicas: the desired number of replicas, lowest value is 0. 680 :param: pod_type: the new pod_type for the index. To learn more about the 681 available pod types, please see [Understanding Indexes](https://docs.pinecone.io/docs/indexes) 682 :param: deletion_protection: If set to 'enabled', the index cannot be deleted. If 'disabled', the index can be deleted. 683 :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. 684 685 This method is used to modify an index's configuration. It can be used to: 686 687 - Scale a pod-based index horizontally using `replicas` 688 - Scale a pod-based index vertically using `pod_type` 689 - Enable or disable deletion protection using `deletion_protection` 690 - Add, change, or remove tags using `tags` 691 692 ## Scaling pod-based indexes 693 694 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. 695 696 ```python 697 import asyncio 698 from pinecone import PineconeAsyncio, PodType 699 700 async def main(): 701 async with PineconeAsyncio() as pc: 702 await pc.configure_index( 703 name="my_index", 704 replicas=2, 705 pod_type=PodType.P1_X2 706 ) 707 708 asyncio.run(main()) 709 ``` 710 711 After providing these new configurations, you must call `describe_index` to see the status of the index as the changes are applied. 712 713 ## Enabling or disabling deletion protection 714 715 To enable or disable deletion protection, pass the `deletion_protection` parameter to the `configure_index` method. When deletion protection 716 is enabled, the index cannot be deleted with the `delete_index` method. 717 718 ```python 719 import asyncio 720 from pinecone import PineconeAsyncio, DeletionProtection 721 722 async def main(): 723 async with PineconeAsyncio() as pc: 724 # Enable deletion protection 725 await pc.configure_index( 726 name="my_index", 727 deletion_protection=DeletionProtection.ENABLED 728 ) 729 730 # Call describe_index to see the change was applied. 731 desc = await pc.describe_index("my_index") 732 assert desc.deletion_protection == "enabled" 733 734 # Disable deletion protection 735 await pc.configure_index( 736 name="my_index", 737 deletion_protection=DeletionProtection.DISABLED 738 ) 739 740 asyncio.run(main()) 741 ``` 742 743 ## Adding, changing, or removing tags 744 745 To add, change, or remove tags, pass the `tags` parameter to the `configure_index` method. When tags are passed using `configure_index`, 746 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. 747 748 ```python 749 import asyncio 750 751 from pinecone import PineconeAsyncio 752 753 async def main(): 754 async with PineconeAsyncio() as pc: 755 # Add a tag 756 await pc.configure_index(name="my_index", tags={"environment": "staging"}) 757 758 # Change a tag 759 await pc.configure_index(name="my_index", tags={"environment": "production"}) 760 761 # Remove a tag 762 await pc.configure_index(name="my_index", tags={"environment": ""}) 763 764 # Call describe_index to view the tags are changed 765 await pc.describe_index("my_index") 766 print(desc.tags) 767 768 asyncio.run(main()) 769 ``` 770 """ 771 pass
Parameters
- name: the name of the Index
- replicas: the desired number of replicas, lowest value is 0.
- pod_type: the new pod_type for the index. To learn more about the available pod types, please see pinecone.control.pinecone.io/docs/indexes">Understanding Indexes
- deletion_protection: If set to 'enabled', the index cannot be deleted. If 'disabled', the index can be deleted.
- 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.
This method is used to modify an index's configuration. It can be used to:
- Scale a pod-based index horizontally using
replicas - Scale a pod-based index vertically using
pod_type - Enable or disable deletion protection using
deletion_protection - Add, change, or remove tags using
tags
Scaling pod-based indexes
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.
import asyncio
from pinecone import PineconeAsyncio, PodType
async def main():
async with PineconeAsyncio() as pc:
await pc.configure_index(
name="my_index",
replicas=2,
pod_type=PodType.P1_X2
)
asyncio.run(main())
After providing these new configurations, you must call describe_index to see the status of the index as the changes are applied.
Enabling or disabling deletion protection
To enable or disable deletion protection, pass the deletion_protection parameter to the configure_index method. When deletion protection
is enabled, the index cannot be deleted with the delete_index method.
import asyncio
from pinecone import PineconeAsyncio, DeletionProtection
async def main():
async with PineconeAsyncio() as pc:
# Enable deletion protection
await pc.configure_index(
name="my_index",
deletion_protection=DeletionProtection.ENABLED
)
# Call describe_index to see the change was applied.
desc = await pc.describe_index("my_index")
assert desc.deletion_protection == "enabled"
# Disable deletion protection
await pc.configure_index(
name="my_index",
deletion_protection=DeletionProtection.DISABLED
)
asyncio.run(main())
Adding, changing, or removing tags
To add, change, or remove tags, pass the tags parameter to the configure_index method. When tags are passed using configure_index,
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.
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
# Add a tag
await pc.configure_index(name="my_index", tags={"environment": "staging"})
# Change a tag
await pc.configure_index(name="my_index", tags={"environment": "production"})
# Remove a tag
await pc.configure_index(name="my_index", tags={"environment": ""})
# Call describe_index to view the tags are changed
await pc.describe_index("my_index")
print(desc.tags)
asyncio.run(main())
@abstractmethod
async def
create_collection(self, name: str, source: str):
773 @abstractmethod 774 async def create_collection(self, name: str, source: str): 775 """Create a collection from a pod-based index 776 777 :param name: Name of the collection 778 :param source: Name of the source index 779 """ 780 pass
Create a collection from a pod-based index
Parameters
- name: Name of the collection
- source: Name of the source index
@abstractmethod
async def
list_collections(self) -> pinecone.models.collection_list.CollectionList:
782 @abstractmethod 783 async def list_collections(self) -> CollectionList: 784 """List all collections 785 786 ```python 787 import asyncio 788 from pinecone import PineconeAsyncio 789 790 async def main(): 791 pc = PineconeAsyncio() 792 793 collections = await pc.list_collections() 794 for collection in collections: 795 print(collection.name) 796 print(collection.source) 797 798 # You can also iterate specifically over 799 # a list of collection names by calling 800 # the .names() helper. 801 collection_name = "my_collection" 802 collections = await pc.list_collections() 803 if collection_name in collections.names(): 804 print('Collection exists') 805 806 await pc.close() 807 808 asyncio.run(main()) 809 ``` 810 """ 811 pass
List all collections
import asyncio
from pinecone import PineconeAsyncio
async def main():
pc = PineconeAsyncio()
collections = await pc.list_collections()
for collection in collections:
print(collection.name)
print(collection.source)
# You can also iterate specifically over
# a list of collection names by calling
# the .names() helper.
collection_name = "my_collection"
collections = await pc.list_collections()
if collection_name in collections.names():
print('Collection exists')
await pc.close()
asyncio.run(main())
@abstractmethod
async def
delete_collection(self, name: str):
813 @abstractmethod 814 async def delete_collection(self, name: str): 815 """Describes a collection. 816 :param: The name of the collection 817 :return: Description of the collection 818 819 ```python 820 import asyncio 821 from pinecone import PineconeAsyncio 822 823 async def main(): 824 async with PineconeAsyncio() as pc: 825 826 description = await pc.describe_collection("my_collection") 827 print(description.name) 828 print(description.source) 829 print(description.status) 830 print(description.size) 831 832 asyncio.run(main()) 833 ``` 834 """ 835 pass
Describes a collection.
Parameters
- The name of the collection
Returns
Description of the collection
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
description = await pc.describe_collection("my_collection")
print(description.name)
print(description.source)
print(description.status)
print(description.size)
asyncio.run(main())
@abstractmethod
async def
describe_collection(self, name: str):
837 @abstractmethod 838 async def describe_collection(self, name: str): 839 """Describes a collection. 840 :param: The name of the collection 841 :return: Description of the collection 842 843 ```python 844 import asyncio 845 from pinecone import PineconeAsyncio 846 847 848 async def main(): 849 async with PineconeAsyncio() as pc: 850 description = await pc.describe_collection("my_collection") 851 print(description.name) 852 print(description.source) 853 print(description.status) 854 print(description.size) 855 856 asyncio.run(main()) 857 ``` 858 """ 859 pass
Describes a collection.
Parameters
- The name of the collection
Returns
Description of the collection
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio() as pc:
description = await pc.describe_collection("my_collection")
print(description.name)
print(description.source)
print(description.status)
print(description.size)
asyncio.run(main())
@abstractmethod
def
IndexAsyncio(self, host, **kwargs):
861 @abstractmethod 862 def IndexAsyncio(self, host, **kwargs): 863 """ 864 Build an asyncio-compatible client for index data operations. 865 866 :param host: The host url of the index. 867 868 ```python 869 import os 870 import asyncio 871 872 from pinecone import PineconeAsyncio 873 874 api_key = os.environ.get("PINECONE_API_KEY") 875 index_host = os.environ.get("PINECONE_INDEX_HOST") 876 877 async def main(): 878 async with Pinecone(api_key=api_key) as pc: 879 async with pc.Index(host=index_host) as idx: 880 # Now you're ready to perform data operations 881 await index.query(vector=[...], top_k=10) 882 883 asyncio.run(main()) 884 ``` 885 886 To find your host url, you can use the `describe_index`. Or, alternatively, the 887 host is displayed in the Pinecone web console. 888 889 ```python 890 import os 891 import asyncio 892 893 from pinecone import PineconeAsyncio 894 895 async def main(): 896 async with PineconeAsyncio( 897 api_key=os.environ.get("PINECONE_API_KEY") 898 ) as pc: 899 host = await pc.describe_index('index-name').host 900 901 asyncio.run(main()) 902 ``` 903 904 ## Alternative setup 905 906 Like instances of the `PineconeAsyncio` class, instances of `IndexAsyncio` have async context that 907 needs to be cleaned up when you are done with it in order to avoid error messages about unclosed session from 908 aiohttp. Nesting these in code is a bit cumbersome, so if you are only planning to do data operations you 909 may prefer to setup the `IndexAsyncio` object via the `Pinecone` class which will avoid creating an outer async context. 910 911 ```python 912 import os 913 import asyncio 914 from pinecone import Pinecone 915 916 api_key = os.environ.get("PINECONE_API_KEY") 917 918 async def main(): 919 pc = Pinecone(api_key=api_key) # sync client, so no async context to worry about 920 921 async with pc.AsyncioIndex(host='your_index_host') as idx: 922 # Now you're ready to perform data operations 923 await idx.query(vector=[...], top_k=10) 924 925 ``` 926 """ 927 pass
Build an asyncio-compatible client for index data operations.
Parameters
- host: The host url of the index.
import os
import asyncio
from pinecone import PineconeAsyncio
api_key = os.environ.get("PINECONE_API_KEY")
index_host = os.environ.get("PINECONE_INDEX_HOST")
async def main():
async with Pinecone(api_key=api_key) as pc:
async with pc.Index(host=index_host) as idx:
# Now you're ready to perform data operations
await index.query(vector=[...], top_k=10)
asyncio.run(main())
To find your host url, you can use the describe_index. Or, alternatively, the
host is displayed in the Pinecone web console.
import os
import asyncio
from pinecone import PineconeAsyncio
async def main():
async with PineconeAsyncio(
api_key=os.environ.get("PINECONE_API_KEY")
) as pc:
host = await pc.describe_index('index-name').host
asyncio.run(main())
Alternative setup
Like instances of the PineconeAsyncio class, instances of IndexAsyncio have async context that
needs to be cleaned up when you are done with it in order to avoid error messages about unclosed session from
aiohttp. Nesting these in code is a bit cumbersome, so if you are only planning to do data operations you
may prefer to setup the IndexAsyncio object via the Pinecone class which will avoid creating an outer async context.
import os
import asyncio
from pinecone import Pinecone
api_key = os.environ.get("PINECONE_API_KEY")
async def main():
pc = Pinecone(api_key=api_key) # sync client, so no async context to worry about
async with pc.AsyncioIndex(host='your_index_host') as idx:
# Now you're ready to perform data operations
await idx.query(vector=[...], top_k=10)