Quickstart
This guide explains how to set up a Pinecone vector database in minutes.
Before you begin
-
If you haven't already, sign up for a free Pinecone account.
On the free Starter plan, you get one project and one index with enough resources for testing Pinecone and for running small applications. Although the Starter plan does not support all Pinecone features, it's easy to upgrade when you're ready.
-
If you'd prefer to get started in your browser, use the "Hello, Pinecone!" colab notebook.
1. Install a Pinecone client
Pinecone exposes a simple REST API for interacting with your vector database. You can use the API directly, or you can use one of the official Pinecone clients:
pip install pinecone-client
npm install @pinecone-database/pinecone
Currently, Pinecone supports a Python client and a Node.js client. For community-supported clients and other client resources, see Libraries.
2. Get your API key
You need an API key and environment name to make API calls to your Pinecone project. To get your key and environment, follow these steps:
- Open the Pinecone Console.
- Go to API Keys.
- Copy your API key and environment.
3. Initialize your connection
Using your API key and environment, initialize your client connection to Pinecone:
import pinecone
pinecone.init(api_key="YOUR_API_KEY", environment="YOUR_ENVIRONMENT")
import { Pinecone } from '@pinecone-database/pinecone';
const pinecone = new Pinecone({
apiKey: 'YOUR_API_KEY',
environment: 'YOUR_ENVIRONMENT'
})
Note
When using the API directly, each HTTP request must contain an
Api-Key
header that specifies your API key, and your environment must be specified in the URL. You'll see this in all subsequentcurl
examples.
4. Create an index
In Pinecone, you store vector embeddings in indexes. In each index, the vectors share the same dimensionality and distance metric for measuring similarity.
Create an index named "quickstart" that performs nearest-neighbor search using the Euclidean distance metric for 8-dimensional vectors:
pinecone.create_index("quickstart", dimension=8, metric="euclidean")
pinecone.describe_index("quickstart")
await pinecone.createIndex({
name: "quickstart",
dimension: 8,
metric: "euclidean",
});
await pinecone.describeIndex("quickstart");
PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"
# Create the index
curl -X POST "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "quickstart",
"dimension": 8,
"metric": "euclidean"
}'
# Check index status
curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases/quickstart" \
-H "Api-Key: $PINECONE_API_KEY"
5. Insert vectors
Now that you've created your index, insert some sample vectors.
-
Create a client instance that targets the "quickstart" index:
index = pinecone.Index("quickstart")
const index = pinecone.index("quickstart");
# Not applicable
-
Use the
upsert
operation to write 5 8-dimensional vectors into the index:index.upsert( 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]} ] )
await index.upsert([ { "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] } ]);
PINECONE_API_KEY="YOUR_API_KEY" PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT" PINECONE_PROJECT_ID=$( curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/actions/whoami" \ -H "Api-Key: $PINECONE_API_KEY" | jq -r '.project_name' ) curl -X POST "https://quickstart-$PINECONE_PROJECT_ID.svc.$PINECONE_ENVIRONMENT.pinecone.io/vectors/upsert" \ -H "Api-Key: $PINECONE_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. Run a nearest-neighbor search
Query your "quickstart" index for the 3 vectors that are most similar to an example 8-dimensional vector, using the Euclidean distance metric you specified for the index:
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': ''}
const queryResponse = await index.query({
topK: 3,
vector: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
includeValues: true
});
// Returns:
// {
// matches: [{
// id: "C",
// score: 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: ""
// }
PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"
PINECONE_PROJECT_ID=$(
curl "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/actions/whoami" \
-H "Api-Key: $PINECONE_API_KEY" | jq -r '.project_name'
)
curl -X POST "https://quickstart-$PINECONE_PROJECT_ID.svc.$PINECONE_ENVIRONMENT.pinecone.io/query" \
-H "Api-Key: $PINECONE_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": ""
# }
This is a simple example. As you put more demands on Pinecone, you'll see it returning low-latency, accurate results at huge scales, with indexes of up to billions of vectors.
7. Clean up
The Starter plan allows only a single index, so once you're done with the "quickstart" index, use the delete_index
operation to delete it:
pinecone.delete_index("quickstart")
await pinecone.deleteIndex("quickstart");
PINECONE_API_KEY="YOUR_API_KEY"
PINECONE_ENVIRONMENT="YOUR_ENVIRONMENT"
curl -X DELETE "https://controller.$PINECONE_ENVIRONMENT.pinecone.io/databases/quickstart" \
-H "Api-Key: $PINECONE_API_KEY"
Warning
After you delete an index, you cannot use it again.
Next steps
Now that you have a free Pinecone account and experience with basic Pinecone operations, check out our sample applications using common AI patterns, tools, and algorithms, or start inserting your own vector embeddings.
Updated 19 days ago