Quickstart
How to get started with the Pinecone vector database.
This guide explains how to set up a Pinecone vector database in minutes.
1. Install Pinecone client (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 other clients, see Libraries.
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 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")
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
In general, indexes on the Starter (free) plan are archived as collections and deleted after 7 days of inactivity; for indexes created by certain open source projects such as AutoGPT, indexes are archived and deleted after 1 day of inactivity. To prevent this, you can send any API request to Pinecone and the counter will reset.
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.
Updated 5 days ago