|
3 | 3 | > Please remove `pinecone-client` from your project dependencies and add `pinecone` instead to get
|
4 | 4 | > the latest updates.
|
5 | 5 |
|
| 6 | +# Upgrading from `6.x` to `7.x` |
| 7 | + |
| 8 | +There are no intentional breaking changes when moving from v6 to v7 of the SDK. The major version bump reflects the move from calling the `2025-01` to the `2025-04` version of the underlying API. |
| 9 | + |
| 10 | +Some internals of the client have been reorganized or moved, but we've made an effort to alias everything and show warning messages when appropriate. If you experience any unexpected breaking changes that cause you friction while upgrading, let us know and we'll try to smooth it out. |
| 11 | + |
| 12 | +## Useful additions in `7.x` |
| 13 | + |
| 14 | +New Features: |
| 15 | +- [Pinecone Assistant](https://www.pinecone.io/product/assistant/): The assistant plugin is now bundled by default. You can simply start using it without installing anything additional. |
| 16 | +- [Inference API](https://docs.pinecone.io/guides/get-started/overview#inference): List/view models from the model gallery via API |
| 17 | +- [Backups](https://docs.pinecone.io/guides/manage-data/backups-overview): |
| 18 | + - Create backup from serverless index |
| 19 | + - Create serverless index from backup |
| 20 | + - List/view backups |
| 21 | + - List/view backup restore jobs |
| 22 | +- [Bring Your Own Cloud (BYOC)](https://docs.pinecone.io/guides/production/bring-your-own-cloud): |
| 23 | + - Create, list, describe, and delete BYOC indexes |
| 24 | + |
| 25 | +Other improvements: |
| 26 | +- ~70% faster client instantiation time thanks to extensive refactoring to implement lazy loading. This means your app won't waste time loading code for features you're not using. |
| 27 | +- Retries with exponential backoff are now enabled by default for REST calls (implemented for both urllib3 and aiohttp). |
| 28 | +- We're following [PEP 561](https://typing.python.org/en/latest/spec/distributing.html#packaging-typed-libraries) and adding a `py.typed` marker file to indicate inline type information is present in the package. We're still working toward reaching full coverage with our type hints, but including this file allows some tools to find the inline definitions we have already implemented. |
| 29 | + |
| 30 | + |
| 31 | +### Backups for Serverless Indexes |
| 32 | + |
| 33 | +You can create backups from your serverless indexes and use these backups to create new indexes. Some fields such as `record_count` are initially empty but will be populated by the time a backup is ready for use. |
| 34 | + |
| 35 | +```python |
| 36 | +from pinecone import Pinecone |
| 37 | + |
| 38 | +pc = Pinecone() |
| 39 | + |
| 40 | +index_name = 'example-index' |
| 41 | +if not pc.has_index(name=index_name): |
| 42 | + raise Exception('An index must exist before backing it up') |
| 43 | + |
| 44 | +backup = pc.create_backup( |
| 45 | + index_name=index_name, |
| 46 | + backup_name='example-backup', |
| 47 | + description='testing out backups' |
| 48 | +) |
| 49 | +# { |
| 50 | +# "backup_id": "4698a618-7e56-4a44-93bc-fc8f1371aa36", |
| 51 | +# "source_index_name": "example-index", |
| 52 | +# "source_index_id": "ec6fd44c-ab45-4873-97f3-f6b44b67e9bc", |
| 53 | +# "status": "Initializing", |
| 54 | +# "cloud": "aws", |
| 55 | +# "region": "us-east-1", |
| 56 | +# "tags": {}, |
| 57 | +# "name": "example-backup", |
| 58 | +# "description": "testing out backups", |
| 59 | +# "dimension": null, |
| 60 | +# "record_count": null, |
| 61 | +# "namespace_count": null, |
| 62 | +# "size_bytes": null, |
| 63 | +# "created_at": "2025-05-16T18:44:28.480671533Z" |
| 64 | +# } |
| 65 | +``` |
| 66 | + |
| 67 | +Check the status of a backup |
| 68 | + |
| 69 | +```python |
| 70 | +from pinecone import Pinecone |
| 71 | + |
| 72 | +pc = Pinecone() |
| 73 | + |
| 74 | +pc.describe_backup(backup_id='4698a618-7e56-4a44-93bc-fc8f1371aa36') |
| 75 | +# { |
| 76 | +# "backup_id": "4698a618-7e56-4a44-93bc-fc8f1371aa36", |
| 77 | +# "source_index_name": "example-index", |
| 78 | +# "source_index_id": "ec6fd44c-ab45-4873-97f3-f6b44b67e9bc", |
| 79 | +# "status": "Ready", |
| 80 | +# "cloud": "aws", |
| 81 | +# "region": "us-east-1", |
| 82 | +# "tags": {}, |
| 83 | +# "name": "example-backup", |
| 84 | +# "description": "testing out backups", |
| 85 | +# "dimension": 768, |
| 86 | +# "record_count": 1000, |
| 87 | +# "namespace_count": 1, |
| 88 | +# "size_bytes": 289656, |
| 89 | +# "created_at": "2025-05-16T18:44:28.480691Z" |
| 90 | +# } |
| 91 | +``` |
| 92 | + |
| 93 | +You can use `list_backups` to see all of your backups and their current status. If you have a large number of backups, results will be paginated. You can control the pagination with optional parameters for `limit` and `pagination_token`. |
| 94 | + |
| 95 | +```python |
| 96 | + |
| 97 | +from pinecone import Pinecone |
| 98 | + |
| 99 | +pc = Pinecone() |
| 100 | + |
| 101 | +# All backups |
| 102 | +pc.list_backups() |
| 103 | + |
| 104 | +# Only backups associated with a particular index |
| 105 | +pc.list_backups(index_name='my-index') |
| 106 | +``` |
| 107 | + |
| 108 | +To create an index from a backup, use `create_index_from_backup`. |
| 109 | + |
| 110 | +```python |
| 111 | +from pinecone import Pinecone |
| 112 | + |
| 113 | +pc = Pinecone() |
| 114 | + |
| 115 | +pc.create_index_from_backup( |
| 116 | + name='index-from-backup', |
| 117 | + backup_id='4698a618-7e56-4a44-93bc-fc8f1371aa36', |
| 118 | + deletion_protection = "disabled", |
| 119 | + tags={'env': 'testing'}, |
| 120 | +) |
| 121 | +``` |
| 122 | + |
| 123 | +Under the hood, a restore job is created to handle taking data from your backup and loading it into the newly created serverless index. You can check status of pending restore jobs with `pc.list_restore_jobs()` or `pc.describe_restore_job()` |
| 124 | + |
| 125 | +### Explore and discover models available in our Inference API |
| 126 | + |
| 127 | +You can now fetch a dynamic list of models supported by the Inference API. |
| 128 | + |
| 129 | +```python |
| 130 | +from pinecone import Pinecone |
| 131 | + |
| 132 | +pc = Pinecone() |
| 133 | + |
| 134 | +# List all models |
| 135 | +models = pc.inference.list_models() |
| 136 | + |
| 137 | +# List models, with model type filtering |
| 138 | +models = pc.inference.list_models(type="embed") |
| 139 | +models = pc.inference.list_models(type="rerank") |
| 140 | + |
| 141 | +# List models, with vector type filtering |
| 142 | +models = pc.inference.list_models(vector_type="dense") |
| 143 | +models = pc.inference.list_models(vector_type="sparse") |
| 144 | + |
| 145 | +# List models, with both type and vector type filtering |
| 146 | +models = pc.inference.list_models(type="rerank", vector_type="dense") |
| 147 | +``` |
| 148 | + |
| 149 | +Or, if you know the name of a model, you can get just those details |
| 150 | + |
| 151 | +``` |
| 152 | +pc.inference.get_model(model_name='pinecone-rerank-v0') |
| 153 | +# { |
| 154 | +# "model": "pinecone-rerank-v0", |
| 155 | +# "short_description": "A state of the art reranking model that out-performs competitors on widely accepted benchmarks. It can handle chunks up to 512 tokens (1-2 paragraphs)", |
| 156 | +# "type": "rerank", |
| 157 | +# "supported_parameters": [ |
| 158 | +# { |
| 159 | +# "parameter": "truncate", |
| 160 | +# "type": "one_of", |
| 161 | +# "value_type": "string", |
| 162 | +# "required": false, |
| 163 | +# "default": "END", |
| 164 | +# "allowed_values": [ |
| 165 | +# "END", |
| 166 | +# "NONE" |
| 167 | +# ] |
| 168 | +# } |
| 169 | +# ], |
| 170 | +# "modality": "text", |
| 171 | +# "max_sequence_length": 512, |
| 172 | +# "max_batch_size": 100, |
| 173 | +# "provider_name": "Pinecone", |
| 174 | +# "supported_metrics": [] |
| 175 | +# } |
| 176 | +``` |
| 177 | + |
| 178 | +### Client support for BYOC (Bring Your Own Cloud) |
| 179 | + |
| 180 | +For customers using our [BYOC offering](https://docs.pinecone.io/guides/production/bring-your-own-cloud), you can now create indexes and list/describe indexes you have created in your cloud. |
| 181 | + |
| 182 | +```python |
| 183 | +from pinecone import Pinecone, ByocSpec |
| 184 | + |
| 185 | +pc = Pinecone() |
| 186 | + |
| 187 | +pc.create_index( |
| 188 | + name='example-byoc-index', |
| 189 | + dimension=768, |
| 190 | + metric='cosine', |
| 191 | + spec=ByocSpec(environment='my-private-env'), |
| 192 | + tags={ |
| 193 | + 'env': 'testing' |
| 194 | + }, |
| 195 | + deletion_protection='enabled' |
| 196 | +) |
| 197 | +``` |
| 198 | + |
6 | 199 | # Upgrading from `5.x` to `6.x`
|
7 | 200 |
|
8 | 201 | ## Breaking changes in 6.x
|
|
0 commit comments