# 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
For notes on changes between major versions, see [Upgrading](./docs/upgrading.md)
## Prerequisites
- The Pinecone Python SDK is compatible with Python 3.9 and greater. It has been tested with CPython versions from 3.9 to 3.13.
- 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).
## Installation
The Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default the `pinecone` has a minimal set of dependencies, but you can install some extras to unlock additional functionality.
Available extras:
- `pinecone[asyncio]` will add a dependency on `aiohttp` and enable usage of `PineconeAsyncio`, the asyncio-enabled version of the client for use with highly asynchronous modern web frameworks such as FastAPI.
- `pinecone[grpc]` will add dependencies on `grpcio` and related libraries needed to make pinecone data calls such as `upsert` and `query` over [GRPC](https://grpc.io/) for a modest performance improvement. 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 optional dependencies
pip3 install "pinecone[asyncio,grpc]"
```
#### Installing with uv
[uv](https://docs.astral.sh/uv/) is a modern package manager that runs 10-100x faster than pip and supports most pip syntax.
```shell
# Install the latest version
uv install pinecone
# Install the latest version, optional dependencies
uv install "pinecone[asyncio,grpc]"
```
#### Installing with [poetry](https://python-poetry.org/)
```shell
# Install the latest version
poetry add pinecone
# Install the latest version, with optional dependencies
poetry add pinecone --extras asyncio --extras grpc
```
# Quickstart
## Bringing your own vectors to Pinecone
```python
from pinecone import (
Pinecone,
ServerlessSpec,
CloudProvider,
AwsRegion,
VectorType
)
# 1. Instantiate the Pinecone client
pc = Pinecone(api_key='YOUR_API_KEY')
# 2. Create an index
index_config = pc.create_index(
name="index-name",
dimension=1536,
spec=ServerlessSpec(
cloud=CloudProvider.AWS,
region=AwsRegion.US_EAST_1
),
vector_type=VectorType.DENSE
)
# 3. Instantiate an Index client
idx = pc.Index(host=index_config.host)
# 4. Upsert embeddings
idx.upsert(
vectors=[
("id1", [0.1, 0.2, 0.3, 0.4, ...], {"metadata_key": "value1"}),
("id2", [0.2, 0.3, 0.4, 0.5, ...], {"metadata_key": "value2"}),
],
namespace="example-namespace"
)
# 5. Query your index using an embedding
query_embedding = [...] # list should have length == index dimension
idx.query(
vector=query_embedding,
top_k=10,
include_metadata=True,
filter={"metadata_key": { "$eq": "value1" }}
)
```
## Bring your own data using Pinecone integrated inference
```python
from pinecone import (
Pinecone,
CloudProvider,
AwsRegion,
EmbedModel,
)
# 1. Instantiate the Pinecone client
pc = Pinecone(api_key="<<PINECONE_API_KEY>>")
# 2. Create an index configured for use with a particular model
index_config = pc.create_index_for_model(
name="my-model-index",
cloud=CloudProvider.AWS,
region=AwsRegion.US_EAST_1,
embed=IndexEmbed(
model=EmbedModel.Multilingual_E5_Large,
field_map={"text": "my_text_field"}
)
)
# 3. Instantiate an Index client
idx = pc.Index(host=index_config.host)
# 4. Upsert records
idx.upsert_records(
namespace="my-namespace",
records=[
{
"_id": "test1",
"my_text_field": "Apple is a popular fruit known for its sweetness and crisp texture.",
},
{
"_id": "test2",
"my_text_field": "The tech company Apple is known for its innovative products like the iPhone.",
},
{
"_id": "test3",
"my_text_field": "Many people enjoy eating apples as a healthy snack.",
},
{
"_id": "test4",
"my_text_field": "Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.",
},
{
"_id": "test5",
"my_text_field": "An apple a day keeps the doctor away, as the saying goes.",
},
{
"_id": "test6",
"my_text_field": "Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.",
},
],
)
# 5. Search for similar records
from pinecone import SearchQuery, SearchRerank, RerankModel
response = index.search_records(
namespace="my-namespace",
query=SearchQuery(
inputs={
"text": "Apple corporation",
},
top_k=3
),
rerank=SearchRerank(
model=RerankModel.Bge_Reranker_V2_M3,
rank_fields=["my_text_field"],
top_n=3,
),
)
```
## More information on usage
Detailed information on specific ways of using the SDK are covered in these other pages.
- Store and query your vectors
- [Serverless Indexes](./docs/db_control/serverless-indexes.md)
- [Pod Indexes](./docs/db_control/pod-indexes.md)
- [Working with vectors](./docs/db_data/index-usage-byov.md)
- [Inference API](./docs/inference-api.md)
- [FAQ](./docs/faq.md)
# Issues & Bugs
If you notice bugs or have feedback, please [file an issue](https://github.com/pinecone-io/pinecone-python-client/issues).
You can also get help in the [Pinecone Community Forum](https://community.pinecone.io/).
# 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.9",
"maintainer_email": null,
"keywords": "Pinecone, vector, database, cloud",
"author": "Pinecone Systems, Inc.",
"author_email": "support@pinecone.io",
"download_url": "https://files.pythonhosted.org/packages/3d/aa/acbfc236698c2b11d53711a86a35f533423b3553e0859255cdd2ced3c6c3/pinecone-6.0.1.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\n## Documentation\n\n- [**Reference Documentation**](https://sdk.pinecone.io/python/index.html)\n\n### Upgrading the SDK\n\nFor notes on changes between major versions, see [Upgrading](./docs/upgrading.md)\n\n## Prerequisites\n\n- The Pinecone Python SDK is compatible with Python 3.9 and greater. It has been tested with CPython versions from 3.9 to 3.13.\n- 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).\n\n## Installation\n\nThe Pinecone Python SDK is distributed on PyPI using the package name `pinecone`. By default the `pinecone` has a minimal set of dependencies, but you can install some extras to unlock additional functionality.\n\nAvailable extras:\n\n- `pinecone[asyncio]` will add a dependency on `aiohttp` and enable usage of `PineconeAsyncio`, the asyncio-enabled version of the client for use with highly asynchronous modern web frameworks such as FastAPI.\n- `pinecone[grpc]` will add dependencies on `grpcio` and related libraries needed to make pinecone data calls such as `upsert` and `query` over [GRPC](https://grpc.io/) for a modest performance improvement. 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 optional dependencies\npip3 install \"pinecone[asyncio,grpc]\"\n```\n\n#### Installing with uv\n\n[uv](https://docs.astral.sh/uv/) is a modern package manager that runs 10-100x faster than pip and supports most pip syntax.\n\n```shell\n# Install the latest version\nuv install pinecone\n\n# Install the latest version, optional dependencies\nuv install \"pinecone[asyncio,grpc]\"\n```\n\n#### Installing with [poetry](https://python-poetry.org/)\n\n```shell\n# Install the latest version\npoetry add pinecone\n\n# Install the latest version, with optional dependencies\npoetry add pinecone --extras asyncio --extras grpc\n```\n\n# Quickstart\n\n## Bringing your own vectors to Pinecone\n\n```python\nfrom pinecone import (\n Pinecone,\n ServerlessSpec,\n CloudProvider,\n AwsRegion,\n VectorType\n)\n\n# 1. Instantiate the Pinecone client\npc = Pinecone(api_key='YOUR_API_KEY')\n\n# 2. Create an index\nindex_config = pc.create_index(\n name=\"index-name\",\n dimension=1536,\n spec=ServerlessSpec(\n cloud=CloudProvider.AWS,\n region=AwsRegion.US_EAST_1\n ),\n vector_type=VectorType.DENSE\n)\n\n# 3. Instantiate an Index client\nidx = pc.Index(host=index_config.host)\n\n# 4. Upsert embeddings\nidx.upsert(\n vectors=[\n (\"id1\", [0.1, 0.2, 0.3, 0.4, ...], {\"metadata_key\": \"value1\"}),\n (\"id2\", [0.2, 0.3, 0.4, 0.5, ...], {\"metadata_key\": \"value2\"}),\n ],\n namespace=\"example-namespace\"\n)\n\n# 5. Query your index using an embedding\nquery_embedding = [...] # list should have length == index dimension\nidx.query(\n vector=query_embedding,\n top_k=10,\n include_metadata=True,\n filter={\"metadata_key\": { \"$eq\": \"value1\" }}\n)\n```\n\n## Bring your own data using Pinecone integrated inference\n\n```python\nfrom pinecone import (\n Pinecone,\n CloudProvider,\n AwsRegion,\n EmbedModel,\n)\n\n# 1. Instantiate the Pinecone client\npc = Pinecone(api_key=\"<<PINECONE_API_KEY>>\")\n\n# 2. Create an index configured for use with a particular model\nindex_config = pc.create_index_for_model(\n name=\"my-model-index\",\n cloud=CloudProvider.AWS,\n region=AwsRegion.US_EAST_1,\n embed=IndexEmbed(\n model=EmbedModel.Multilingual_E5_Large,\n field_map={\"text\": \"my_text_field\"}\n )\n)\n\n# 3. Instantiate an Index client\nidx = pc.Index(host=index_config.host)\n\n# 4. Upsert records\nidx.upsert_records(\n namespace=\"my-namespace\",\n records=[\n {\n \"_id\": \"test1\",\n \"my_text_field\": \"Apple is a popular fruit known for its sweetness and crisp texture.\",\n },\n {\n \"_id\": \"test2\",\n \"my_text_field\": \"The tech company Apple is known for its innovative products like the iPhone.\",\n },\n {\n \"_id\": \"test3\",\n \"my_text_field\": \"Many people enjoy eating apples as a healthy snack.\",\n },\n {\n \"_id\": \"test4\",\n \"my_text_field\": \"Apple Inc. has revolutionized the tech industry with its sleek designs and user-friendly interfaces.\",\n },\n {\n \"_id\": \"test5\",\n \"my_text_field\": \"An apple a day keeps the doctor away, as the saying goes.\",\n },\n {\n \"_id\": \"test6\",\n \"my_text_field\": \"Apple Computer Company was founded on April 1, 1976, by Steve Jobs, Steve Wozniak, and Ronald Wayne as a partnership.\",\n },\n ],\n)\n\n# 5. Search for similar records\nfrom pinecone import SearchQuery, SearchRerank, RerankModel\n\nresponse = index.search_records(\n namespace=\"my-namespace\",\n query=SearchQuery(\n inputs={\n \"text\": \"Apple corporation\",\n },\n top_k=3\n ),\n rerank=SearchRerank(\n model=RerankModel.Bge_Reranker_V2_M3,\n rank_fields=[\"my_text_field\"],\n top_n=3,\n ),\n)\n```\n\n## More information on usage\n\nDetailed information on specific ways of using the SDK are covered in these other pages.\n\n- Store and query your vectors\n - [Serverless Indexes](./docs/db_control/serverless-indexes.md)\n - [Pod Indexes](./docs/db_control/pod-indexes.md)\n - [Working with vectors](./docs/db_data/index-usage-byov.md)\n\n- [Inference API](./docs/inference-api.md)\n- [FAQ](./docs/faq.md)\n\n\n# Issues & Bugs\n\nIf you notice bugs or have feedback, please [file an issue](https://github.com/pinecone-io/pinecone-python-client/issues).\n\nYou can also get help in the [Pinecone Community Forum](https://community.pinecone.io/).\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": "6.0.1",
"project_urls": {
"Documentation": "https://pinecone.io/docs",
"Homepage": "https://www.pinecone.io"
},
"split_keywords": [
"pinecone",
" vector",
" database",
" cloud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "95dfc65cd8c825953561e7fe70addd0b41e20560abda8f54ab429384cf94f7a1",
"md5": "c41e8748ba6dbba2f56689bf32f4fe1b",
"sha256": "9088c6fc85bc1d70b259b108c59df2b3687a82da491123be8f3c7dfef051ada8"
},
"downloads": -1,
"filename": "pinecone-6.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c41e8748ba6dbba2f56689bf32f4fe1b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 421359,
"upload_time": "2025-02-10T14:57:20",
"upload_time_iso_8601": "2025-02-10T14:57:20.912166Z",
"url": "https://files.pythonhosted.org/packages/95/df/c65cd8c825953561e7fe70addd0b41e20560abda8f54ab429384cf94f7a1/pinecone-6.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3daaacbfc236698c2b11d53711a86a35f533423b3553e0859255cdd2ced3c6c3",
"md5": "321a9db6787b5bdf08dbe36947e514e7",
"sha256": "2fbca13153d32d1a012a12eb10472bd5dbb645be8e441381ad88349d8b2198bb"
},
"downloads": -1,
"filename": "pinecone-6.0.1.tar.gz",
"has_sig": false,
"md5_digest": "321a9db6787b5bdf08dbe36947e514e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 174677,
"upload_time": "2025-02-10T14:57:22",
"upload_time_iso_8601": "2025-02-10T14:57:22.839964Z",
"url": "https://files.pythonhosted.org/packages/3d/aa/acbfc236698c2b11d53711a86a35f533423b3553e0859255cdd2ced3c6c3/pinecone-6.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-10 14:57:22",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pinecone"
}
JSON