Quickstart guide

This guide explains how to set up a Pinecone client and get a production-ready similarity search service up and running in minutes.

Pinecone is tested on Python 3.6+. Coming soon: Clients for Java and Go.

1. Install Pinecone

Use the following commands at the command line (the terminal) to install Pinecone:

pip install pinecone-client

For more information on how to install Pinecone clients, including troubleshooting, see Installation.

2. Get and Verify your Pinecone API key

To use Pinecone, you must have an API key. Get one at: Get an API key. We'll email you an API key. No credit card required.

Let’s make sure your Pinecone API key works.

pythoncurl
import pinecone

pinecone.init(api_key=">>>YOUR_API_KEY<<<")
curl -i -H 'Api-Key: YOUR_API_KEY' http://controller.beta.pinecone.io/actions/whoami

If you don't get back an error message, then it's working.

3. Hello, Pinecone!

We've created a code sample that walks you through the steps for getting a simple Pinecone index up and running. You can either:

  • Use the "Hello, Pinecone!" colab notebook to write and execute Python in your browser.
  • Copy the commands below into your local installation of Python.
  • Use the curl API commands described below.

Prerequisites if you're using a local installation of Python

1. Set up Pinecone

import pinecone
pinecone.init(api_key=">>>YOUR_API_KEY<<<")

2. Install Pandas

To use the sample code below, you must install Pandas. Pandas is a Python package for data analysis, and a popular tool used by many applications. It is not required in order to use the Python client.

To install the Python client, type:

pip install pandas

Using Pinecone

1. Create an index.

In this case, we create an index named "hello-pinecone" that will perform approximate nearest-neighbor search using Euclidean distance for 128-dimensional vectors:

pythoncurl
pinecone.create_index("hello-pinecone", index_type='approximated', dimension=128, metric="euclidean")
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  https://controller.beta.pinecone.io/databases \
  -d '{
    "name": "hello-pinecone",
    "dimension": 128,
    "indexType": "approximated",
    "metric": "euclidean"
  }'

2. Connect to the index:

index = pinecone.Index("hello-pinecone")

3. Insert the data.

You'll perform upsert operations in the index. This call will insert a new vector in the index or update the vector if the id was already present:

pythoncurl
# Import Pandas data analysis package
import pandas as pd

# Generate sample data as a pandas dataframe
df = pd.DataFrame(data={
    "id": ["A", "B", "C", "D", "E"],
    "vector": [[0.1]*128, [0.2]*128, [0.3]*128, [0.4]*128, [0.5]*128]
})

# insert the data
index.upsert(vectors=zip(df.id, df.vector)) # insert vectors
curl -i -X POST \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  'https://hello-pinecone-example-project.svc.beta.pinecone.io/vectors/upsert' \
  -d '{
    "vectors": [
      {
        "id": "id-0",
        "values": [
          1.22, 2.23, 3.73  // ...
        ]
      }
    ]
  }'

Note: For the above curl example and those below, replace hello-pinecone-example-project.svc.beta.pinecone.io with {index-name}-{project-name}.svc.beta.pinecone.io.

You can retrieve {project-name} from the Pinecone management console or from the /actions/whoami curl example above.

4. Get statistics about the index's contents.

For example: The vector count per namespace and the number of dimensions.

pythoncurl
index.summarize()
curl -i -H 'Api-Key: YOUR_API_KEY_HERE' \
  'https://hello-pinecone-example-project.svc.beta.pinecone.io/summarize'

5. Query the index and get similar vectors:

pythoncurl
index.query(queries=[[0.1] * 128], top_k=3)
curl -i -X POST \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  'https://hello-pinecone-example-project.svc.beta.pinecone.io/query' \
  -d '{
    "topK": 3,
    "queries": [
      {
        "values": [
          1.524, 2.23, 3.73  // ...
        ]
      }
    ]
  }'

6. Delete the index.

Delete the index once you are sure that you do not want to use it anymore:

pythoncurl
pinecone.delete_index("hello-pinecone")
curl -i -X DELETE \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  https://controller.beta.pinecone.io/databases/hello-pinecone

Note: When the index is deleted, you cannot use it again.

Next steps

Now that you’re successfully making indexes with your API key, you can:

  • Read more how-to guides

  • Dive into the example apps and the Pinecone REST APIs.

  • Learn more about vector databases and similarity search as a service