Package: pinecone-client
Pinecone Python Client ·The official Pinecone Python client.For more information, see the docs athttps://www.pinecone.io/docs/DocumentationIf you are upgrading from a2.2.xversion of the client, check out thev3 Migration Guide.Reference DocumentationExample codeMany 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 client can be used, explore some of our many Jupyter notebooks in theexamplesrepository.PrerequisitesThe Pinecone Python client is compatible with Python 3.8 and greater.InstallationThere are two flavors of the Pinecone python client. The default client installed from PyPI aspinecone-clienthas 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 client implementation that relies on gRPC for data operations. See the guide ontuning performance.Installing with pip# Install the latest versionpip3installpinecone-client# Install the latest version, with extra grpc dependenciespip3install"pinecone-client[grpc]"# Install a specific versionpip3installpinecone-client==3.0.0# Install a specific version, with grpc extraspip3install"pinecone-client[grpc]"==3.0.0Installing with poetry# Install the latest versionpoetryaddpinecone# Install the latest version, with grpc extraspoetryaddpinecone--extrasgrpc# Install a specific versionpoetryaddpinecone-client==3.0.0# Install a specific version, with grpc extraspoetryaddpinecone-client==3.0.0--extrasgrpcUsageInitializing the clientBefore you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard athttps://app.pinecone.io.Using environment variablesThePineconeclass is your main entry point into the Pinecone python SDK. If you have set your API Key in thePINECONE_API_KEYenvironment variable, you can instantiate the client with no other arguments.frompineconeimportPineconepc=Pinecone()# This reads the PINECONE_API_KEY env varUsing a configuration objectIf 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 forapi_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 samePINECONE_API_KEYvariable that the client implicitly checks for.Configuration passed with keyword arguments takes precedent over environment variables.importosfrompineconeimportPineconepc=Pinecone(api_key=os.environ.get('CUSTOM_VAR'))Working with GRPC (for improved performance)If you've followed instructions above to install with optionalgrpcextras, you can unlock some performance improvements by working with an alternative version of the client imported from thepinecone.grpcsubpackage.importosfrompinecone.grpcimportPineconeGRPCpc=PineconeGRPC(api_key=os.environ.get('PINECONE_API_KEY'))# From here on, everything is identical to the REST-based client.index=pc.Index(host='my-index-8833ca1.svc.us-east1-gcp.pinecone.io')index.upsert(vectors=[])index.query(vector=[...],top_key=10)IndexesCreate IndexCreate a serverless index[!WARNING]Serverless indexes are inpublic previewand are available only on AWS in theus-west-2region. Check thecurrent limitationsand test thoroughly before using it in production.frompineconeimportPinecone,ServerlessSpecpc=Pinecone(api_key='<<PINECONE_API_KEY>>')pc.create_index(name='my-index',dimension=1536,metric='euclidean',spec=ServerlessSpec(cloud='aws',region='us-west-2'))Create a pod indexThe following example creates an index without a metadata
configuration. By default, Pinecone indexes all metadata.frompineconeimportPinecone,PodSpecpc=Pinecone(api_key='<<PINECONE_API_KEY>>')pc.create_index(name="example-index",dimension=1536,metric="cosine",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.frompineconeimportPinecone,PodSpecpc=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 indexesThe following example returns all indexes in your project.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')forindexinpc.list_indexes():print(index['name'])Describe indexThe following example returns information about the indexexample-index.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')index_description=pc.describe_index("example-index")Delete an indexThe following example deletes the index namedexample-index.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')pc.delete_index("example-index")Scale replicasThe following example changes the number of replicas forexample-index.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')new_number_of_replicas=4pc.configure_index("example-index",replicas=new_number_of_replicas)Describe index statisticsThe following example returns statistics about the indexexample-index.importosfrompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')index=pc.Index(host=os.environ.get('INDEX_HOST'))index_stats_response=index.describe_index_stats()Upsert vectorsThe following example upserts vectors toexample-index.importosfrompineconeimportPineconepc=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 indexThe following example queries the indexexample-indexwith metadata
filtering.importosfrompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')# Find your index host by calling describe_index# through the Pinecone web consoleindex=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 vectorsThe following example deletes vectors by ID.importosfrompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')# Find your index host by calling describe_index# through the Pinecone web consoleindex=pc.Index(host=os.environ.get('INDEX_HOST'))delete_response=index.delete(ids=["vec1","vec2"],namespace="example-namespace")Fetch vectorsThe following example fetches vectors by ID.importosfrompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')# Find your index host by calling describe_index# through the Pinecone web consoleindex=pc.Index(host=os.environ.get('INDEX_HOST'))fetch_response=index.fetch(ids=["vec1","vec2"],namespace="example-namespace")Update vectorsThe following example updates vectors by ID.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')# Find your index host by calling describe_index# through the Pinecone web consoleindex=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 vectorsThelistandlist_paginatedmethods 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.Thelistmethod returns a generator that handles pagination on your behalf.frompineconeimportPineconepc=Pinecone(api_key='xxx')index=pc.Index(host='hosturl')# To iterate over all result pages using a generator functionnamespace='foo-namespace'foridsinindex.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 withlist_paginated.frompineconeimportPineconepc=Pinecone(api_key='xxx')index=pc.Index(host='hosturl')# For manual control over paginationresults=index.list_paginated(prefix='pref',limit=3,namespace='foo',pagination_token='eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ==')print(results.namespace)# 'foo'print([v.idforvinresults.vectors])# ['pref1', 'pref2', 'pref3']print(results.pagination.next)# 'eyJza2lwX3Bhc3QiOiI5IiwicHJlZml4IjpudWxsfQ=='print(results.usage)# { 'read_units': 1 }CollectionsCreate collectionThe following example creates the collectionexample-collectionfromexample-index.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')pc.create_collection(name="example-collection",source="example-index")List collectionsThe following example returns a list of the collections in the current project.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')active_collections=pc.list_collections()Describe a collectionThe following example returns a description of the collectionexample-collection.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')collection_description=pc.describe_collection("example-collection")Delete a collectionThe following example deletes the collectionexample-collection.frompineconeimportPineconepc=Pinecone(api_key='<<PINECONE_API_KEY>>')pc.delete_collection("example-collection")ContributingIf you'd like to make a contribution, or get setup locally to develop the Pinecone python client, please see ourcontributing guide