# Pinecone Python SDK
 [](https://github.com/pinecone-io/pinecone-python-client/actions/workflows/pr.yaml)
The official Pinecone Python SDK.
For more information, see the docs at https://docs.pinecone.io
## Documentation
- [**Reference Documentation**](https://sdk.pinecone.io/python/index.html)
### Upgrading the SDK
#### Upgrading from `4.x` to `5.x`
As part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (`openapi_config`) was removed in favor of individual configuration options such as `proxy_url`, `proxy_headers`, and `ssl_ca_certs`. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.
It is no longer necessary to install a separate plugin, `pinecone-plugin-inference`, to try out the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference); that plugin is now installed by default in the v5 SDK. See [usage instructions below](#inference-api).
#### Older releases
- **Upgrading to `4.x`** : For this upgrade you are unlikely to be impacted by breaking changes unless you are using the `grpc` extras (see install steps below). Read full details in these [v4 Release Notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0).
- **Upgrading to `3.x`**: Many things were changed in the v3 SDK to pave the way for Pinecone's new Serverless index offering. These changes are covered in detail in the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3). Serverless indexes are only available in `3.x` release versions or greater.
### Example code
Many of the brief examples shown in this README are using very small vectors to keep the documentation concise, but most real world usage will involve much larger embedding vectors. To see some more realistic examples of how this SDK can be used, explore some of our many Jupyter notebooks in the [examples](https://github.com/pinecone-io/examples) repository.
## Prerequisites
The Pinecone Python SDK is compatible with Python 3.8 and greater.
## Installation
There are two flavors of the Pinecone Python SDK. The default flavor installed from PyPI as `pinecone` has a minimal set of dependencies and interacts with Pinecone via HTTP requests.
If you are aiming to maximimize performance, you can install additional gRPC dependencies to access an alternate SDK implementation that relies on gRPC for data operations. See the guide on [tuning performance](https://docs.pinecone.io/docs/performance-tuning).
### Installing with pip
```shell
# Install the latest version
pip3 install pinecone
# Install the latest version, with extra grpc dependencies
pip3 install "pinecone[grpc]"
# Install a specific version
pip3 install pinecone==5.0.0
# Install a specific version, with grpc extras
pip3 install "pinecone[grpc]"==5.0.0
```
### Installing with poetry
```shell
# Install the latest version
poetry add pinecone
# Install the latest version, with grpc extras
poetry add pinecone --extras grpc
# Install a specific version
poetry add pinecone==5.0.0
# Install a specific version, with grpc extras
poetry add pinecone==5.0.0 --extras grpc
```
## Usage
### Initializing the client
Before you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard at [https://app.pinecone.io](https://app.pinecone.io).
#### Using environment variables
The `Pinecone` class is your main entry point into the Pinecone python SDK. If you have set your API Key in the `PINECONE_API_KEY` environment variable, you can instantiate the client with no other arguments.
```python
from pinecone import Pinecone
pc = Pinecone() # This reads the PINECONE_API_KEY env var
```
#### Using configuration keyword params
If you prefer to pass configuration in code, for example if you have a complex application that needs to interact with multiple different Pinecone projects, the constructor accepts a keyword argument for `api_key`.
If you pass configuration in this way, you can have full control over what name to use for the environment variable, sidestepping any issues that would result
from two different client instances both needing to read the same `PINECONE_API_KEY` variable that the client implicitly checks for.
Configuration passed with keyword arguments takes precedence over environment variables.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key=os.environ.get('CUSTOM_VAR'))
```
### 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 forwarded to `urllib3`, which is the underlying library currently used by the Pinecone SDK to make HTTP requests. You may find it helpful to refer to the [urllib3 documentation on working with proxies](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#http-and-https-proxies) while troubleshooting these settings.
Here is a basic example:
```python
from pinecone import Pinecone
pc = Pinecone(
api_key='YOUR_API_KEY',
proxy_url='https://your-proxy.com'
)
pc.list_indexes()
```
If your proxy requires authentication, you can pass those values in a header dictionary using the `proxy_headers` parameter.
```python
from pinecone import Pinecone
import urllib3 import make_headers
pc = Pinecone(
api_key='YOUR_API_KEY',
proxy_url='https://your-proxy.com',
proxy_headers=make_headers(proxy_basic_auth='username:password')
)
pc.list_indexes()
```
### Using proxies with self-signed certificates
By default the Pinecone Python SDK will perform SSL certificate verification
using the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/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.
```python
from pinecone import Pinecone
import urllib3 import make_headers
pc = Pinecone(
api_key="YOUR_API_KEY",
proxy_url='https://your-proxy.com',
proxy_headers=make_headers(proxy_basic_auth='username:password'),
ssl_ca_certs='path/to/cert-bundle.pem'
)
pc.list_indexes()
```
### 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.
```python
from pinecone import Pinecone
import urllib3 import make_headers
pc = Pinecone(
api_key='YOUR_API_KEY',
proxy_url='https://your-proxy.com',
proxy_headers=make_headers(proxy_basic_auth='username:password'),
ssl_ca_certs='path/to/cert-bundle.pem',
ssl_verify=False
)
pc.list_indexes()
```
### Working with GRPC (for improved performance)
If you've followed instructions above to install with optional `grpc` extras, you can unlock some performance improvements by working with an alternative version of the SDK imported from the `pinecone.grpc` subpackage.
```python
import os
from pinecone.grpc import PineconeGRPC
pc = PineconeGRPC(api_key=os.environ.get('PINECONE_API_KEY'))
# From here on, everything is identical to the REST-based SDK.
index = pc.Index(host='my-index-8833ca1.svc.us-east1-gcp.pinecone.io')
index.upsert(vectors=[])
index.query(vector=[...], top_key=10)
```
# Indexes
## Create Index
### Create a serverless index
The following example creates a serverless index in the `us-west-2`
region of AWS. For more information on serverless and regional availability, see [Understanding indexes](https://docs.pinecone.io/guides/indexes/understanding-indexes#serverless-indexes).
```python
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
pc.create_index(
name='my-index',
dimension=1536,
metric='euclidean',
deletion_protection='enabled',
spec=ServerlessSpec(
cloud='aws',
region='us-west-2'
)
)
```
### Create a pod index
The following example creates an index without a metadata
configuration. By default, Pinecone indexes all metadata.
```python
from pinecone import Pinecone, PodSpec
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
pc.create_index(
name="example-index",
dimension=1536,
metric="cosine",
deletion_protection='enabled',
spec=PodSpec(
environment='us-west-2',
pod_type='p1.x1'
)
)
```
Pod indexes support many optional configuration fields. For example,
the following example creates an index that only indexes
the "color" metadata field. Queries against this index
cannot filter based on any other metadata field.
```python
from pinecone import Pinecone, PodSpec
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
metadata_config = {
"indexed": ["color"]
}
pc.create_index(
"example-index-2",
dimension=1536,
spec=PodSpec(
environment='us-west-2',
pod_type='p1.x1',
metadata_config=metadata_config
)
)
```
## List indexes
The following example returns all indexes in your project.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
for index in pc.list_indexes():
print(index['name'])
```
## Describe index
The following example returns information about the index `example-index`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
index_description = pc.describe_index("example-index")
```
## Delete an index
The following example deletes the index named `example-index`. Only indexes which are not protected by deletion protection may be deleted.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
pc.delete_index("example-index")
```
## Scale replicas
The following example changes the number of replicas for `example-index`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
new_number_of_replicas = 4
pc.configure_index("example-index", replicas=new_number_of_replicas)
```
## Configuring deletion protection
If you would like to enable deletion protection, which prevents an index from being deleted, the `configure_index` method also handles that via an optional `deletion_protection` keyword argument.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
# To enable deletion protection
pc.configure_index("example-index", deletion_protection='enabled')
# Disable deletion protection
pc.configure_index("example-index", deletion_protection='disabled')
# Call describe index to verify the configuration change has been applied
desc = pc.describe_index("example-index")
print(desc.deletion_protection)
```
## Describe index statistics
The following example returns statistics about the index `example-index`.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
index = pc.Index(host=os.environ.get('INDEX_HOST'))
index_stats_response = index.describe_index_stats()
```
## Upsert vectors
The following example upserts vectors to `example-index`.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
index = pc.Index(host=os.environ.get('INDEX_HOST'))
upsert_response = index.upsert(
vectors=[
("vec1", [0.1, 0.2, 0.3, 0.4], {"genre": "drama"}),
("vec2", [0.2, 0.3, 0.4, 0.5], {"genre": "action"}),
],
namespace="example-namespace"
)
```
## Query an index
The following example queries the index `example-index` with metadata
filtering.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
# Find your index host by calling describe_index
# through the Pinecone web console
index = pc.Index(host=os.environ.get('INDEX_HOST'))
query_response = index.query(
namespace="example-namespace",
vector=[0.1, 0.2, 0.3, 0.4],
top_k=10,
include_values=True,
include_metadata=True,
filter={
"genre": {"$in": ["comedy", "documentary", "drama"]}
}
)
```
## Delete vectors
The following example deletes vectors by ID.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
# Find your index host by calling describe_index
# through the Pinecone web console
index = pc.Index(host=os.environ.get('INDEX_HOST'))
delete_response = index.delete(ids=["vec1", "vec2"], namespace="example-namespace")
```
## Fetch vectors
The following example fetches vectors by ID.
```python
import os
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
# Find your index host by calling describe_index
# through the Pinecone web console
index = pc.Index(host=os.environ.get('INDEX_HOST'))
fetch_response = index.fetch(ids=["vec1", "vec2"], namespace="example-namespace")
```
## Update vectors
The following example updates vectors by ID.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
# Find your index host by calling describe_index
# through the Pinecone web console
index = pc.Index(host=os.environ.get('INDEX_HOST'))
update_response = index.update(
id="vec1",
values=[0.1, 0.2, 0.3, 0.4],
set_metadata={"genre": "drama"},
namespace="example-namespace"
)
```
## List vectors
The `list` and `list_paginated` methods can be used to list vector ids matching a particular id prefix.
With clever assignment of vector ids, this can be used to help model hierarchical relationships between
different vectors such as when there are embeddings for multiple chunks or fragments related to the
same document.
The `list` method returns a generator that handles pagination on your behalf.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='xxx')
index = pc.Index(host='hosturl')
# To iterate over all result pages using a generator function
namespace = 'foo-namespace'
for ids in index.list(prefix='pref', limit=3, namespace=namespace):
print(ids) # ['pref1', 'pref2', 'pref3']
# Now you can pass this id array to other methods, such as fetch or delete.
vectors = index.fetch(ids=ids, namespace=namespace)
```
There is also an option to fetch each page of results yourself with `list_paginated`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='xxx')
index = pc.Index(host='hosturl')
# For manual control over pagination
results = index.list_paginated(
prefix='pref',
limit=3,
namespace='foo',
pagination_token='eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='
)
print(results.namespace) # 'foo'
print([v.id for v in results.vectors]) # ['pref1', 'pref2', 'pref3']
print(results.pagination.next) # 'eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='
print(results.usage) # { 'read_units': 1 }
```
# Collections
## Create collection
The following example creates the collection `example-collection` from
`example-index`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
pc.create_collection(
name="example-collection",
source="example-index"
)
```
## List collections
The following example returns a list of the collections in the current project.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
active_collections = pc.list_collections()
```
## Describe a collection
The following example returns a description of the collection
`example-collection`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
collection_description = pc.describe_collection("example-collection")
```
## Delete a collection
The following example deletes the collection `example-collection`.
```python
from pinecone import Pinecone
pc = Pinecone(api_key='<<PINECONE_API_KEY>>')
pc.delete_collection("example-collection")
```
# Inference API
The Pinecone SDK now supports creating embeddings via the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference).
```python
from pinecone import Pinecone
pc = Pinecone(api_key="YOUR_API_KEY")
model = "multilingual-e5-large"
# Embed documents
text = [
"Turkey is a classic meat to eat at American Thanksgiving.",
"Many people enjoy the beautiful mosques in Turkey.",
]
text_embeddings = pc.inference.embed(
model=model,
inputs=text,
parameters={"input_type": "passage", "truncate": "END"},
)
# Upsert documents into Pinecone index
# Embed a query
query = ["How should I prepare my turkey?"]
query_embeddings = pc.inference.embed(
model=model,
inputs=query,
parameters={"input_type": "query", "truncate": "END"},
)
# Send query to Pinecone index to retrieve similar documents
```
# Contributing
If you'd like to make a contribution, or get setup locally to develop the Pinecone Python SDK, please see our [contributing guide](https://github.com/pinecone-io/pinecone-python-client/blob/main/CONTRIBUTING.md)
Raw data
{
"_id": null,
"home_page": "https://www.pinecone.io",
"name": "pinecone",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "Pinecone, vector, database, cloud",
"author": "Pinecone Systems, Inc.",
"author_email": "support@pinecone.io",
"download_url": "https://files.pythonhosted.org/packages/50/0b/17072d355d80686fc21139a65e3ac359388e1e9d2424fb426cfb3bfb10f9/pinecone-5.4.0.tar.gz",
"platform": null,
"description": "# Pinecone Python SDK \n [](https://github.com/pinecone-io/pinecone-python-client/actions/workflows/pr.yaml)\n\nThe official Pinecone Python SDK.\n\nFor more information, see the docs at https://docs.pinecone.io\n\n## Documentation\n\n- [**Reference Documentation**](https://sdk.pinecone.io/python/index.html)\n\n### Upgrading the SDK\n\n#### Upgrading from `4.x` to `5.x` \n\nAs part of an overall move to stop exposing generated code in the package's public interface, an obscure configuration property (`openapi_config`) was removed in favor of individual configuration options such as `proxy_url`, `proxy_headers`, and `ssl_ca_certs`. All of these properties were available in v3 and v4 releases of the SDK, with deprecation notices shown to affected users.\n\nIt is no longer necessary to install a separate plugin, `pinecone-plugin-inference`, to try out the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference); that plugin is now installed by default in the v5 SDK. See [usage instructions below](#inference-api).\n\n#### Older releases\n\n- **Upgrading to `4.x`** : For this upgrade you are unlikely to be impacted by breaking changes unless you are using the `grpc` extras (see install steps below). Read full details in these [v4 Release Notes](https://github.com/pinecone-io/pinecone-python-client/releases/tag/v4.0.0).\n\n- **Upgrading to `3.x`**: Many things were changed in the v3 SDK to pave the way for Pinecone's new Serverless index offering. These changes are covered in detail in the [**v3 Migration Guide**](https://canyon-quilt-082.notion.site/Pinecone-Python-SDK-v3-0-0-Migration-Guide-056d3897d7634bf7be399676a4757c7b#a21aff70b403416ba352fd30e300bce3). Serverless indexes are only available in `3.x` release versions or greater.\n\n### Example code\n\nMany of the brief examples shown in this README are using very small vectors to keep the documentation concise, but most real world usage will involve much larger embedding vectors. To see some more realistic examples of how this SDK can be used, explore some of our many Jupyter notebooks in the [examples](https://github.com/pinecone-io/examples) repository.\n\n## Prerequisites\n\nThe Pinecone Python SDK is compatible with Python 3.8 and greater.\n\n## Installation\n\nThere are two flavors of the Pinecone Python SDK. The default flavor installed from PyPI as `pinecone` has a minimal set of dependencies and interacts with Pinecone via HTTP requests.\n\nIf you are aiming to maximimize performance, you can install additional gRPC dependencies to access an alternate SDK implementation that relies on gRPC for data operations. See the guide on [tuning performance](https://docs.pinecone.io/docs/performance-tuning).\n\n### Installing with pip\n\n```shell\n# Install the latest version\npip3 install pinecone\n\n# Install the latest version, with extra grpc dependencies\npip3 install \"pinecone[grpc]\"\n\n# Install a specific version\npip3 install pinecone==5.0.0\n\n# Install a specific version, with grpc extras\npip3 install \"pinecone[grpc]\"==5.0.0\n```\n\n### Installing with poetry\n\n```shell\n# Install the latest version\npoetry add pinecone\n\n# Install the latest version, with grpc extras\npoetry add pinecone --extras grpc\n\n# Install a specific version\npoetry add pinecone==5.0.0\n\n# Install a specific version, with grpc extras\npoetry add pinecone==5.0.0 --extras grpc\n```\n\n## Usage\n\n### Initializing the client\n\nBefore you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard at [https://app.pinecone.io](https://app.pinecone.io).\n\n#### Using environment variables\n\nThe `Pinecone` class is your main entry point into the Pinecone python SDK. If you have set your API Key in the `PINECONE_API_KEY` environment variable, you can instantiate the client with no other arguments.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone() # This reads the PINECONE_API_KEY env var\n```\n\n#### Using configuration keyword params\n\nIf you prefer to pass configuration in code, for example if you have a complex application that needs to interact with multiple different Pinecone projects, the constructor accepts a keyword argument for `api_key`.\n\nIf you pass configuration in this way, you can have full control over what name to use for the environment variable, sidestepping any issues that would result\nfrom two different client instances both needing to read the same `PINECONE_API_KEY` variable that the client implicitly checks for.\n\nConfiguration passed with keyword arguments takes precedence over environment variables.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key=os.environ.get('CUSTOM_VAR'))\n```\n\n### Proxy configuration\n\nIf your network setup requires you to interact with Pinecone via a proxy, you will need\nto pass additional configuration using optional keyword parameters. These optional parameters are forwarded to `urllib3`, which is the underlying library currently used by the Pinecone SDK to make HTTP requests. You may find it helpful to refer to the [urllib3 documentation on working with proxies](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#http-and-https-proxies) while troubleshooting these settings.\n\nHere is a basic example:\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(\n api_key='YOUR_API_KEY',\n proxy_url='https://your-proxy.com'\n)\n\npc.list_indexes()\n```\n\nIf your proxy requires authentication, you can pass those values in a header dictionary using the `proxy_headers` parameter.\n\n```python\nfrom pinecone import Pinecone\nimport urllib3 import make_headers\n\npc = Pinecone(\n api_key='YOUR_API_KEY',\n proxy_url='https://your-proxy.com',\n proxy_headers=make_headers(proxy_basic_auth='username:password')\n)\n\npc.list_indexes()\n```\n\n### Using proxies with self-signed certificates\n\nBy default the Pinecone Python SDK will perform SSL certificate verification\nusing the CA bundle maintained by Mozilla in the [certifi](https://pypi.org/project/certifi/) package.\n\nIf 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.\n\n```python\nfrom pinecone import Pinecone\nimport urllib3 import make_headers\n\npc = Pinecone(\n api_key=\"YOUR_API_KEY\",\n proxy_url='https://your-proxy.com',\n proxy_headers=make_headers(proxy_basic_auth='username:password'),\n ssl_ca_certs='path/to/cert-bundle.pem'\n)\n\npc.list_indexes()\n```\n\n### Disabling SSL verification\n\nIf you would like to disable SSL verification, you can pass the `ssl_verify`\nparameter with a value of `False`. We do not recommend going to production with SSL verification disabled.\n\n```python\nfrom pinecone import Pinecone\nimport urllib3 import make_headers\n\npc = Pinecone(\n api_key='YOUR_API_KEY',\n proxy_url='https://your-proxy.com',\n proxy_headers=make_headers(proxy_basic_auth='username:password'),\n ssl_ca_certs='path/to/cert-bundle.pem',\n ssl_verify=False\n)\n\npc.list_indexes()\n\n```\n\n### Working with GRPC (for improved performance)\n\nIf you've followed instructions above to install with optional `grpc` extras, you can unlock some performance improvements by working with an alternative version of the SDK imported from the `pinecone.grpc` subpackage.\n\n```python\nimport os\nfrom pinecone.grpc import PineconeGRPC\n\npc = PineconeGRPC(api_key=os.environ.get('PINECONE_API_KEY'))\n\n# From here on, everything is identical to the REST-based SDK.\nindex = pc.Index(host='my-index-8833ca1.svc.us-east1-gcp.pinecone.io')\n\nindex.upsert(vectors=[])\nindex.query(vector=[...], top_key=10)\n```\n\n# Indexes\n\n## Create Index\n\n### Create a serverless index\n\nThe following example creates a serverless index in the `us-west-2`\nregion of AWS. For more information on serverless and regional availability, see [Understanding indexes](https://docs.pinecone.io/guides/indexes/understanding-indexes#serverless-indexes).\n\n```python\nfrom pinecone import Pinecone, ServerlessSpec\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\npc.create_index(\n name='my-index',\n dimension=1536,\n metric='euclidean',\n deletion_protection='enabled',\n spec=ServerlessSpec(\n cloud='aws',\n region='us-west-2'\n )\n)\n```\n\n### Create a pod index\n\nThe following example creates an index without a metadata\nconfiguration. By default, Pinecone indexes all metadata.\n\n```python\nfrom pinecone import Pinecone, PodSpec\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\npc.create_index(\n name=\"example-index\",\n dimension=1536,\n metric=\"cosine\",\n deletion_protection='enabled',\n spec=PodSpec(\n environment='us-west-2',\n pod_type='p1.x1'\n )\n)\n```\n\nPod indexes support many optional configuration fields. For example,\nthe following example creates an index that only indexes\nthe \"color\" metadata field. Queries against this index\ncannot filter based on any other metadata field.\n\n```python\nfrom pinecone import Pinecone, PodSpec\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\nmetadata_config = {\n \"indexed\": [\"color\"]\n}\n\npc.create_index(\n \"example-index-2\",\n dimension=1536,\n spec=PodSpec(\n environment='us-west-2',\n pod_type='p1.x1',\n metadata_config=metadata_config\n )\n)\n```\n\n## List indexes\n\nThe following example returns all indexes in your project.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\nfor index in pc.list_indexes():\n print(index['name'])\n```\n\n## Describe index\n\nThe following example returns information about the index `example-index`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\nindex_description = pc.describe_index(\"example-index\")\n```\n\n## Delete an index\n\nThe following example deletes the index named `example-index`. Only indexes which are not protected by deletion protection may be deleted.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\npc.delete_index(\"example-index\")\n```\n\n## Scale replicas\n\nThe following example changes the number of replicas for `example-index`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\nnew_number_of_replicas = 4\npc.configure_index(\"example-index\", replicas=new_number_of_replicas)\n```\n\n## Configuring deletion protection\n\nIf you would like to enable deletion protection, which prevents an index from being deleted, the `configure_index` method also handles that via an optional `deletion_protection` keyword argument.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\n# To enable deletion protection\npc.configure_index(\"example-index\", deletion_protection='enabled')\n\n# Disable deletion protection\npc.configure_index(\"example-index\", deletion_protection='disabled')\n\n# Call describe index to verify the configuration change has been applied\ndesc = pc.describe_index(\"example-index\")\nprint(desc.deletion_protection)\n```\n\n## Describe index statistics\n\nThe following example returns statistics about the index `example-index`.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\nindex_stats_response = index.describe_index_stats()\n```\n\n## Upsert vectors\n\nThe following example upserts vectors to `example-index`.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\nupsert_response = index.upsert(\n vectors=[\n (\"vec1\", [0.1, 0.2, 0.3, 0.4], {\"genre\": \"drama\"}),\n (\"vec2\", [0.2, 0.3, 0.4, 0.5], {\"genre\": \"action\"}),\n ],\n namespace=\"example-namespace\"\n)\n```\n\n## Query an index\n\nThe following example queries the index `example-index` with metadata\nfiltering.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\n# Find your index host by calling describe_index\n# through the Pinecone web console\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\nquery_response = index.query(\n namespace=\"example-namespace\",\n vector=[0.1, 0.2, 0.3, 0.4],\n top_k=10,\n include_values=True,\n include_metadata=True,\n filter={\n \"genre\": {\"$in\": [\"comedy\", \"documentary\", \"drama\"]}\n }\n)\n```\n\n## Delete vectors\n\nThe following example deletes vectors by ID.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\n# Find your index host by calling describe_index\n# through the Pinecone web console\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\ndelete_response = index.delete(ids=[\"vec1\", \"vec2\"], namespace=\"example-namespace\")\n```\n\n## Fetch vectors\n\nThe following example fetches vectors by ID.\n\n```python\nimport os\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\n# Find your index host by calling describe_index\n# through the Pinecone web console\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\nfetch_response = index.fetch(ids=[\"vec1\", \"vec2\"], namespace=\"example-namespace\")\n```\n\n## Update vectors\n\nThe following example updates vectors by ID.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\n# Find your index host by calling describe_index\n# through the Pinecone web console\nindex = pc.Index(host=os.environ.get('INDEX_HOST'))\n\nupdate_response = index.update(\n id=\"vec1\",\n values=[0.1, 0.2, 0.3, 0.4],\n set_metadata={\"genre\": \"drama\"},\n namespace=\"example-namespace\"\n)\n```\n\n## List vectors\n\nThe `list` and `list_paginated` methods can be used to list vector ids matching a particular id prefix.\nWith clever assignment of vector ids, this can be used to help model hierarchical relationships between\ndifferent vectors such as when there are embeddings for multiple chunks or fragments related to the\nsame document.\n\nThe `list` method returns a generator that handles pagination on your behalf.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='xxx')\nindex = pc.Index(host='hosturl')\n\n# To iterate over all result pages using a generator function\nnamespace = 'foo-namespace'\nfor ids in index.list(prefix='pref', limit=3, namespace=namespace):\n print(ids) # ['pref1', 'pref2', 'pref3']\n\n # Now you can pass this id array to other methods, such as fetch or delete.\n vectors = index.fetch(ids=ids, namespace=namespace)\n```\n\nThere is also an option to fetch each page of results yourself with `list_paginated`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='xxx')\nindex = pc.Index(host='hosturl')\n\n# For manual control over pagination\nresults = index.list_paginated(\n prefix='pref',\n limit=3,\n namespace='foo',\n pagination_token='eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='\n)\nprint(results.namespace) # 'foo'\nprint([v.id for v in results.vectors]) # ['pref1', 'pref2', 'pref3']\nprint(results.pagination.next) # 'eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='\nprint(results.usage) # { 'read_units': 1 }\n```\n\n# Collections\n\n## Create collection\n\nThe following example creates the collection `example-collection` from\n`example-index`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\npc.create_collection(\n name=\"example-collection\",\n source=\"example-index\"\n)\n```\n\n## List collections\n\nThe following example returns a list of the collections in the current project.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\nactive_collections = pc.list_collections()\n```\n\n## Describe a collection\n\nThe following example returns a description of the collection\n`example-collection`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\ncollection_description = pc.describe_collection(\"example-collection\")\n```\n\n## Delete a collection\n\nThe following example deletes the collection `example-collection`.\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key='<<PINECONE_API_KEY>>')\n\npc.delete_collection(\"example-collection\")\n```\n\n# Inference API\n\nThe Pinecone SDK now supports creating embeddings via the [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference).\n\n```python\nfrom pinecone import Pinecone\n\npc = Pinecone(api_key=\"YOUR_API_KEY\")\nmodel = \"multilingual-e5-large\"\n\n# Embed documents\ntext = [\n \"Turkey is a classic meat to eat at American Thanksgiving.\",\n \"Many people enjoy the beautiful mosques in Turkey.\",\n]\ntext_embeddings = pc.inference.embed(\n model=model,\n inputs=text,\n parameters={\"input_type\": \"passage\", \"truncate\": \"END\"},\n)\n\n# Upsert documents into Pinecone index\n\n# Embed a query\nquery = [\"How should I prepare my turkey?\"]\nquery_embeddings = pc.inference.embed(\n model=model,\n inputs=query,\n parameters={\"input_type\": \"query\", \"truncate\": \"END\"},\n)\n\n# Send query to Pinecone index to retrieve similar documents\n```\n\n# Contributing\n\nIf you'd like to make a contribution, or get setup locally to develop the Pinecone Python SDK, please see our [contributing guide](https://github.com/pinecone-io/pinecone-python-client/blob/main/CONTRIBUTING.md)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Pinecone client and SDK",
"version": "5.4.0",
"project_urls": {
"Documentation": "https://pinecone.io/docs",
"Homepage": "https://www.pinecone.io"
},
"split_keywords": [
"pinecone",
" vector",
" database",
" cloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2c771434fcc750a693e180422f6e3aedc4e65ca7184e1ad083109b9bc113edb4",
"md5": "4bab16958b60a6259cd5f20d81463daf",
"sha256": "3eb19bb79fc0aadf973a37ef67392ef1be512e5a9fa808347ad6ef2da4d220df"
},
"downloads": -1,
"filename": "pinecone-5.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4bab16958b60a6259cd5f20d81463daf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 427316,
"upload_time": "2024-11-13T20:34:17",
"upload_time_iso_8601": "2024-11-13T20:34:17.277242Z",
"url": "https://files.pythonhosted.org/packages/2c/77/1434fcc750a693e180422f6e3aedc4e65ca7184e1ad083109b9bc113edb4/pinecone-5.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "500b17072d355d80686fc21139a65e3ac359388e1e9d2424fb426cfb3bfb10f9",
"md5": "9bb7b5bef00b40799499c51717756625",
"sha256": "c68c9142d1bafd10cf72a94c309486303491a3ea4af9b630ea319f3172ca3ea8"
},
"downloads": -1,
"filename": "pinecone-5.4.0.tar.gz",
"has_sig": false,
"md5_digest": "9bb7b5bef00b40799499c51717756625",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 191682,
"upload_time": "2024-11-13T20:34:18",
"upload_time_iso_8601": "2024-11-13T20:34:18.671802Z",
"url": "https://files.pythonhosted.org/packages/50/0b/17072d355d80686fc21139a65e3ac359388e1e9d2424fb426cfb3bfb10f9/pinecone-5.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-13 20:34:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pinecone"
}
JSON