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.

1. Install Pinecone (optional)

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

info

Pinecone is tested on Python 3.6+.

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

Copy
Copied
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
Copy
Copied
import pinecone

pinecone.init(api_key=">>>YOUR_API_KEY<<<", environment="us-west1-gcp")
Copy
Copied
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

By default, YOUR_ENVIRONMENT is us-west1-gcp.

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
Copy
Copied
import pinecone
pinecone.init(api_key=">>>YOUR_API_KEY<<<", environment="us-west1-gcp")
Copy
Copied
# 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
Copy
Copied
pinecone.create_index("hello-pinecone", index_type="approximated", dimension=8, metric="euclidean")
Copy
Copied
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Api-Key: YOUR_API_KEY_HERE' \
  https://controller.YOUR_ENVIRONMENT.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
Copy
Copied
pinecone.list_indexes()
# Returns:
# ['hello-pinecone']
Copy
Copied
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/databases \
  -H "Api-Key: YOUR_API_KEY"
# Output:
# ["hello-pinecone"]

4. Connect to the index:

pythoncurl
Copy
Copied
index = pinecone.Index("hello-pinecone")
Copy
Copied
# 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
Copy
Copied
# Insert sample data (5 8-dimensional vectors)
index.upsert([
    ("A", [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]),
    ("B", [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]),
    ("C", [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]),
    ("D", [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]),
    ("E", [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5])
])
Copy
Copied
curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.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.YOUR_ENVIRONMENT.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".
  • YOUR_ENVIRONMENT is the region where Pinecone is deployed. By default, it is us-west1-gcp. Free accounts are limited to us-west1-gcp.
pythoncurl
Copy
Copied
pinecone.whoami()
Copy
Copied
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

6. Get statistics about the index's contents.

pythoncurl
Copy
Copied
index.describe_index_stats()
# Returns:
# {'dimension': 8, 'namespaces': {'': {'vector_count': 5}}}
Copy
Copied
curl -i https://hello-pinecone-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.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
Copy
Copied
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': ''}]}
Copy
Copied
curl -i -X POST https://hello-pinecone-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.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
Copy
Copied
pinecone.delete_index("hello-pinecone")
Copy
Copied
curl -i -X DELETE https://controller.YOUR_ENVIRONMENT.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