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.

Video overview

1. Install Pinecone (optional)

info

This step is optional: Do this step only if you want to use the Python client.

Pinecone is tested on Python 3.6+.

Coming soon: Clients for Java and Go.

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<<<", environment="us-west1-gcp")
curl -i https://controller.us-west1-gcp.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

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.

1. Initialize Pinecone

pythoncurl
import pinecone
pinecone.init(api_key=">>>YOUR_API_KEY<<<", environment="us-west1-gcp")
# Not applicable
Getting your API key

You should have received an API key from Get and Verify your Pinecone API key above.

2. Create an index.

In this case, we create an index named "hello-pinecone" that will perform approximate nearest-neighbor search using Euclidean distance for 8-dimensional vectors. Real applications will likely use much higher dimensional vectors than this.

Index creation should take roughly a minute or less.

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

3. Once your index is created, you should see its name included when you list your indexes:

pythoncurl
pinecone.list_indexes()
# Returns:
# ['hello-pinecone']
curl -i https://controller.us-west1-gcp.pinecone.io/databases \
  -H "Api-Key: YOUR_API_KEY"
# Output:
# ["hello-pinecone"]

4. Connect to the index:

pythoncurl
index = pinecone.Index("hello-pinecone")
# Not applicable

5. 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
# Sample data (5 8-dimensional vectors)
ids = ["A", "B", "C", "D", "E"]
vectors = [
    [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1],
    [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2],
    [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4],
    [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]
]
# Insert the data
index.upsert(vectors=zip(ids, vectors))
curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.us-west1-gcp.pinecone.io/vectors/upsert \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "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]
      }
    ]
  }'
About your index endpoint

For curl and other direct API calls to a Pinecone index, you'll need to know the dedicated endpoint for your index.

Index endpoints take the form https://{index-name}-{project-name}.svc.us-west1-gcp.pinecone.io, where:

  • {index-name} is the name you gave your index when you created it. The examples here are using "hello-pinecone".
  • {project-name} is the Pinecone project name that your API key is associated with. This can be retrieved using the whoami operation as follows. The examples here are using "YOUR_PROJECT".
pythoncurl
pinecone.whoami()
curl -i https://controller.us-west1-gcp.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

6. Get statistics about the index's contents.

pythoncurl
index.describe_index_stats()
# Returns:
# {'dimension': 8, 'namespaces': {'': {'vector_count': 5}}}
curl -i https://hello-pinecone-YOUR_PROJECT.svc.us-west1-gcp.pinecone.io/describe_index_stats \
  -H 'Api-Key: YOUR_API_KEY'

# Output:
# {
#   "namespaces": {
#     "": {
#       "vectorCount": 5
#     }
#   },
#   "dimension": 8
# }

7. Query the index and get similar vectors:

pythoncurl
index.query(
  queries=[[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]],
  top_k=3,
  include_values=True
)
# Returns:
# {'results': [{'matches': [{'id': 'C',
#                            'score': -1.76717265e-07,
#                            'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
#                           {'id': 'B',
#                            'score': 0.080000028,
#                            'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]},
#                           {'id': 'D',
#                            'score': 0.0800001323,
#                            'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]}],
#               'namespace': ''}]}
curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.us-west1-gcp.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "queries": [
      {"values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]}
    ],
    "topK": 3,
    "includeValues": true
  }'

# Output:
# {
#   "results":[
#     {
#       "matches":[
#         {
#           "id": "C",
#           "score": -1.76717265e-07,
#           "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
#         },
#         {
#           "id": "B",
#           "score": 0.080000028,
#           "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
#         },
#         {
#           "id": "D",
#           "score": 0.0800001323,
#           "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
#         }
#       ],
#       "namespace": ""
#     }
#   ]
# }

8. 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 https://controller.us-west1-gcp.pinecone.io/databases/hello-pinecone \
  -H 'Api-Key: YOUR_API_KEY'
warning

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