Quickstart

How to get started with the Pinecone vector database.

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.

Use the following shell command 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. To find your API key, open the Pinecone console, click your project name, and click API Keys. This view also displays the environment for your project. Note both your API key and your environment.

To verify that your Pinecone API key works, use the following commands:

import pinecone

pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/actions/whoami -H 'Api-Key: YOUR_API_KEY'

.

If you don't receive an error message, then your API key is valid.

3. Hello, Pinecone!

You can complete the remaining steps in three ways:

  • 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 below.

1. Initialize Pinecone

import pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
# Not applicable

2. Create an index.

The commands below create an index named "quickstart" that performs approximate nearest-neighbor search using the Euclidean distance metric for 8-dimensional vectors.

Index creation takes roughly a minute.

pinecone.create_index("quickstart", dimension=8, metric="euclidean", pod_type="p1")
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": "quickstart",
    "dimension": 8,
    "metric": "euclidean"
  }'

⚠️

Warning

Indexes on the Starter (free) plan are deleted after 14 days of inactivity. To prevent this, send any API request or log into the console. This will count as activity.

3. Retrieve a list of your indexes.

Once your index is created, its name appears in the index list.

Use the following commands to return a list of your indexes.

pinecone.list_indexes()
# Returns:
# ['quickstart']
curl -i https://controller.YOUR_ENVIRONMENT.pinecone.io/databases \
  -H "Api-Key: YOUR_API_KEY"
# Output:
# ["quickstart"]

4. Connect to the index (Client only).

Before you can query your index using a client, you must connect to the index.

Use the following commands to connect to your index.

index = pinecone.Index("quickstart")
# Not applicable

5. Insert the data.

To ingest vectors into your index, use the upsert operation.

The upsert operation inserts a new vector in the index or updates the vector if a vector with the same ID is already present.

The following commands upsert 5 8-dimensional vectors into your index.

# Upsert 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])
])
curl -i -X POST https://quickstart-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]
      }
    ]
  }'

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

ℹ️

Note

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

6. Get statistics about your index.

The following commands return statistics about the contents of your index.

index.describe_index_stats()
# Returns:
# {'dimension': 8, 'index_fullness': 0.0, 'namespaces': {'': {'vector_count': 5}}}
curl -i https://quickstart-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.

The following example queries the index for the three (3) vectors that are most similar to an example 8-dimensional vector using the Euclidean distance metric specified in step 2 ("Create an index.") above.

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': ''}
curl -i -X POST https://quickstart-YOUR_PROJECT.svc.YOUR_ENVIRONMENT.pinecone.io/query \
  -H 'Api-Key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
    "topK": 3,
    "includeValues": true
  }'

# Output:
# {
#       "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.

Once you no longer need the index, use the delete_index operation to delete it.

The following commands delete the index.

pinecone.delete_index("quickstart")
curl -i -X DELETE https://controller.YOUR_ENVIRONMENT.pinecone.io/databases/quickstart \
  -H 'Api-Key: YOUR_API_KEY'

⚠️

Warning

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

Next steps

Now that you’re successfully making indexes with your API key, you can start inserting data or view more examples.