Quickstart
This guide shows you how to set up a Pinecone vector database in minutes using Pinecone's new API.
Before you begin
-
If you haven't already, sign up for a Standard or Enterprise Pinecone account. You'll get $100 in serverless credits that will last you far beyond this quickstart.
-
If you're on the Starter plan, upgrade to Standard or Enterprise to get your $100 in serverless credits.
-
If you don't want to provide a credit card, you can create a free pod-based index.
1. Install a Pinecone client
Pinecone exposes a simple REST API for interacting with its vector database. You can use the API directly, or you can use one of the official Python or Node.js clients:
pip install pinecone-client
npm install @pinecone-database/pinecone
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 to make API calls to your Pinecone project. To get your key, follow these steps:
- Open the Pinecone Console.
- Go to API Keys.
- Copy your API key.
3. Initialize your client connection
Using your API key, initialize your client connection to Pinecone:
from pinecone import Pinecone
pc = Pinecone(api_key='YOUR_API_KEY')
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone({
apiKey: 'YOUR_API_KEY'
});
Note
When using the API directly, each HTTP request must contain an
Api-Key
header that specifies your API key. You'll see this in all subsequentcurl
examples.
4. Create a serverless index
In Pinecone, you store vector embeddings in indexes. The vectors in any index you create must share the same dimensionality and distance metric for measuring similarity.
Use the following code to create a serverless index named "quickstart" that performs nearest-neighbor search using the Euclidean distance similarity metric for vectors of 8 dimensions:
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key='YOUR_API_KEY')
pc.create_index(
name="quickstart",
dimension=8,
metric="euclidean",
spec=ServerlessSpec(
cloud='aws',
region='us-west-2'
)
)
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone({
apiKey: 'YOUR_API_KEY'
});
await pc.createIndex({
name: 'quickstart',
dimension: 8,
metric: 'euclidean',
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2'
}
}
})
PINECONE_API_KEY = "YOUR_API_KEY"
curl -s -X POST "https://api.pinecone.io/indexes" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Api-Key: $PINECONE_API_KEY" \
-d '{
"name": "quickstart",
"dimension": 1536,
"metric": "cosine",
"spec": {
"serverless": {
"cloud": "aws",
"region": "us-west-2"
}
}
}'
5. Upsert vectors
Now that you've created your index, upsert sample vectors into 2 distinct namespaces.
Namespaces let you partition vectors within a single index. Although optional, they are a best practice for speeding up queries, which can be filtered by namespace, and for complying with multi-tenancy requirements.
-
Create a client instance that targets the "quickstart" index:
index = pc.Index("quickstart")
const index = pc.index("quickstart");
# Not applicable
-
Use the
upsert
operation to write 8 8-dimensional vectors into 2 distinct namespaces:index.upsert( vectors=[ {"id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]}, {"id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}, {"id": "vec3", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]}, {"id": "vec4", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]} ], namespace="ns1" ) index.upsert( vectors=[ {"id": "vec5", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5]}, {"id": "vec6", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}, {"id": "vec7", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]}, {"id": "vec8", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]} ], namespace="ns2" )
await index.namespace("ns1").upsert([ { "id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "vec3", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "vec4", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ]); await index.namespace("ns2").upsert([ { "id": "vec5", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "vec6", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "vec7", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "vec8", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ]);
# The `POST` requests below uses the unique endpoint for an index. # See https://docs.pinecone.io/docs/get-index-endpoint for details. PINECONE_API_KEY="YOUR_API_KEY" INDEX_HOST="INDEX_HOST" curl -X POST "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "vectors": [ { "id": "vec1", "values": [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] }, { "id": "vec2", "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2] }, { "id": "vec3", "values": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3] }, { "id": "vec4", "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4] } ], "namespace": "ns1" }' curl -X POST "https://$INDEX_HOST/vectors/upsert" \ -H "Api-Key: $PINECONE_API_KEY" \ -H 'Content-Type: application/json' \ -d '{ "vectors": [ { "id": "vec5", "values": [0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5, 0.5] }, { "id": "vec6", "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6] }, { "id": "vec7", "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7] }, { "id": "vec8", "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8] } ], "namespace": "ns2" }'
Note
When upserting larger amounts of data, upsert data in batches of 100-500 vectors over multiple upsert requests.
6. Check the index
Pinecone is eventually consistent, so there can be a delay before your upserted vectors are available to query. Use the describe_index_stats
operation to check if the current vector count matches the number of vectors you upserted:
index.describe_index_stats()
# Returns:
# {'dimension': 8,
# 'index_fullness': 0.0,
# 'namespaces': {'ns1': {'vector_count': 4}, 'ns2': {'vector_count': 4}},
# 'total_vector_count': 8}
const stats = await index.describeIndexStats();
// Returns:
// {
// namespaces: { ns1: { recordCount: 4 }, ns2: { recordCount: 4 } },
// dimension: 8,
// indexFullness: 0.00008,
// totalRecordCount: 8
// }
# The `POST` request below uses the unique endpoint for an index.
# See https://docs.pinecone.io/docs/get-index-endpoint for details.
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl -X POST "https://$INDEX_HOST/describe_index_stats" \
-H "Api-Key: $PINECONE_API_KEY" \
# Output:
# {
# "namespaces": {
# "ns1": {
# "vectorCount": 4
# },
# "ns2": {
# "vectorCount": 4
# }
# },
# "dimension": 8,
# "indexFullness": 0.00008,
# "totalVectorCount": 8
# }
7. Run a similarity search
Query each namespace in your 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(
namespace="ns1",
vector=[0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
top_k=3,
include_values=True
)
index.query(
namespace="ns2",
vector=[0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
top_k=3,
include_values=True
)
# Returns:
# {'matches': [{'id': 'vec3',
# 'score': 0.0,
# 'values': [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]},
# {'id': 'vec4',
# 'score': 0.0799999237,
# 'values': [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]},
# {'id': 'vec2',
# 'score': 0.0800000429,
# 'values': [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]}],
# 'namespace': 'ns1',
# 'usage': {'read_units': 6}}
# {'matches': [{'id': 'vec7',
# 'score': 0.0,
# 'values': [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]},
# {'id': 'vec8',
# 'score': 0.0799999237,
# 'values': [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]},
# {'id': 'vec6',
# 'score': 0.0799999237,
# 'values': [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]}],
# 'namespace': 'ns2',
# 'usage': {'read_units': 6}}
const queryResponse1 = await index.namespace("ns1").query({
topK: 3,
vector: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
includeValues: true
});
const queryResponse2 = await index.namespace("ns2").query({
topK: 3,
vector: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
includeValues: true
});
// Returns:
// {
// matches: [{
// id: "vec3",
// score: 0,
// values: [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3]
// }, {
// id: "vec4",
// score: 0.0799999237,
// values: [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
// }, {
// id: "vec2",
// score: 0.0800000429,
// values: [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
// }],
// namespace: "ns1",
// usage: {readUnits: 6}
// }
// {
// matches: [{
// id: "vec7",
// score: 0,
// values: [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
// }, {
// id: "vec6",
// score: 0.0799999237,
// values: [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
// }, {
// id: "vec8",
// score: 0.0800000429,
// values: [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]
// }],
// namespace: "ns2",
// usage: {readUnits: 6}
// }
# The `POST` requests below uses the unique endpoint for an index.
# See https://docs.pinecone.io/docs/get-index-endpoint for details.
PINECONE_API_KEY="YOUR_API_KEY"
INDEX_HOST="INDEX_HOST"
curl -X POST "https://$INDEX_HOST/query" \
-H "Api-Key: $PINECONE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"namespace": "ns1",
"vector": [0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3, 0.3],
"topK": 3,
"includeValues": true
}'
curl -X POST "https://$INDEX_HOST/query" \
\
-H "Api-Key: $PINECONE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"namespace": "ns2",
"vector": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7],
"topK": 3,
"includeValues": true
}'
# Output:
# {
# "matches":[
# {
# "id": "vec3",
# "score": 0,
# "values": [0.3,0.3,0.3,0.3,0.3,0.3,0.3,0.3]
# },
# {
# "id": "vec2",
# "score": 0.0800000429,
# "values": [0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2, 0.2]
# },
# {
# "id": "vec4",
# "score": 0.0799999237,
# "values": [0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4, 0.4]
# }
# ],
# "namespace": "ns1",
# "usage": {"read_units": 6}
# }
# {
# "matches": [
# {
# "id": "vec7",
# "score": 0,
# "values": [0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7, 0.7]
# },
# {
# "id": "vec6",
# "score": 0.0799999237,
# "values": [0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6, 0.6]
# },
# {
# "id": "vec8",
# "score": 0.0799999237,
# "values": [0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8, 0.8]
# }
# ],
# "namespace": "ns2",
# "usage": {"read_units": 6}
# }
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.
8. Clean up
When you no longer need the "quickstart" index, use the delete_index
operation to delete it:
pc.delete_index("quickstart")
await pc.deleteIndex("quickstart");
PINECONE_API_KEY="YOUR_API_KEY"
curl -s -X -v DELETE "https://api.pinecone.io/indexes/quickstart" \
-H "Accept: application/json" \
-H "Api-Key: $PINECONE_API_KEY"
Warning
After you delete an index, you cannot use it again or recover it.
Next steps
Now that you have a serverless index and experience with basic Pinecone operations, check out our sample applications using common AI patterns, tools, and algorithms, or start upserting your own vector embeddings.
Updated 19 days ago