Before you begin

1. Install a Pinecone client

Pinecone exposes a simple REST API for interacting with your vector database. You can use the API directly, or you can use one of the official Pinecone clients:

pip install pinecone-client

Currently, Pinecone supports a Python client and a Node.js client. For community-supported clients and other client resources, see Libraries.

2. Get your API key

You need an API key and environment name to make API calls to your Pinecone project. To get your key and environment, follow these steps:

  1. Open the Pinecone Console.
  2. Go to API Keys.
  3. Copy your API key and environment.

3. Initialize your connection

Using your API key and environment, initialize your client connection to Pinecone:

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")

When using the API directly, each HTTP request must contain an Api-Key header that specifies your API key, and your environment must be specified in the URL. You’ll see this in all subsequent curl examples.

4. Create an index

In Pinecone, you store vector embeddings in indexes. In each index, the vectors share the same dimensionality and distance metric for measuring similarity.

Create an index named “quickstart” that performs nearest-neighbor search using the Euclidean distance metric for 8-dimensional vectors:

pinecone.create_index("quickstart", dimension=8, metric="euclidean")
pinecone.describe_index("quickstart")

5. Insert vectors

Now that you’ve created your index, insert some sample vectors.

  1. Create a client instance that targets the “quickstart” index:
index = pinecone.Index("quickstart")  
  1. Use the upsert operation to write 5 8-dimensional vectors into the index:
index.upsert(  
  vectors=[  
    {"id": "A", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]},  
    {"id": "B", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},  
    {"id": "C", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},  
    {"id": "D", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},  
    {"id": "E", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}  
  ]  
)  

The curl command above uses the endpoint for your Pinecone index.

When upserting larger amounts of data, upsert data in batches of 100 vectors or fewer over multiple upsert requests.

Query your “quickstart” index for the 3 vectors that are most similar to an example 8-dimensional vector, using the Euclidean distance metric you specified for index:

index.query(
  vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
  top_k=3,
  include_values=True
)
# Returns:
# {'matches': [{'id': 'C',
#               'score': 0.0,
#               'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#              {'id': 'D',
#               'score': 0.0799999237,
#               'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
#              {'id': 'B',
#               'score': 0.0800000429,
#               'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}],
#  'namespace': ''}

This is a simple example. As you put more demands on Pinecone, you’ll see it returning low-latency, accurate results at huge scales, with indexes of up to billions of vectors.

7. Clean up

The Starter plan allows only a single index, so once you’re done with the “quickstart” index, use the delete_index operation to delete it:

pinecone.delete_index("quickstart")

After you delete an index, you cannot use it again.

Next steps

Now that you have a free Pinecone account and experience with basic Pinecone operations, check out our sample applications using common AI patterns, tools, and algorithms, or start inserting your own vector embeddings.

Was this page helpful?