Quickstart

Pinecone provides long-term memory for high-performance AI applications. It’s a managed, cloud-native vector database with a streamlined API and no infrastructure hassles. Pinecone serves fresh, relevant query results with low latency at the scale of billions of vectors.

This guide shows you how to set up and use a Pinecone vector database in minutes.

​

1. Sign up for Pinecone or log in

Sign up for a free Pinecone account or log in to your existing account:

Your API key will display in the next section.

​

2. Get your API key

You need an API key to make API calls to your Pinecone project. Copy your generated key:

PINECONE_API_KEY="{{YOUR_API_KEY}}"

Alternatively, you can get your key from the Pinecone console:

1. Open the Pinecone console.
2. Select your project.
3. Go to API Keys.
4. Copy your API key.

​

3. 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 (via HTTP or gRPC), Node.js, or Java clients:

pip install pinecone-client[grpc]

# To install without gRPC run:
# pip3 install pinecone-client

​

4. Initialize your client connection

Using your API key, initialize your client connection to Pinecone:

from pinecone.grpc import PineconeGRPC as Pinecone
from pinecone import ServerlessSpec

pc = Pinecone(api_key='YOUR_API_KEY')

​

5. Create a serverless index

In Pinecone, an index is the highest-level organizational unit of data, where you define the dimension of vectors to be stored and the similarity metric to be used when querying them. Normally, you choose a dimension and similarity metric based on the embedding model used to create your vectors. For this quickstart, however, you’ll use a configuration that makes it easy to verify your query results.

Create a serverless index named docs-quickstart-index that stores vectors of 2 dimensions and performs nearest-neighbor search using the cosine similarity metric:

index_name = "docs-quickstart-index"

if index_name not in pc.list_indexes().names():
    pc.create_index(
        name=index_name,
        dimension=2,
        metric="cosine",
        spec=ServerlessSpec(
            cloud='aws', 
            region='us-east-1'
        ) 
    ) 

​

6. Upsert vectors

Within an index, vectors are stored in namespaces, and all upserts, queries, and other data operations always target one namespace:

Now that you’ve created your index, target the docs-quickstart-index index and use the upsert operation to write six 2-dimensional vectors into 2 distinct namespaces:

index = pc.Index(index_name)

index.upsert(
    vectors=[
        {"id": "vec1", "values": [1.0, 1.5]},
        {"id": "vec2", "values": [2.0, 1.0]},
        {"id": "vec3", "values": [0.1, 3.0]},
    ],
    namespace="ns1"
)

index.upsert(
    vectors=[
        {"id": "vec1", "values": [1.0, -2.5]},
        {"id": "vec2", "values": [3.0, -2.0]},
        {"id": "vec3", "values": [0.5, -1.5]},
    ],
    namespace="ns2"
)

​

7. 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:

print(index.describe_index_stats())

# Returns:
# {'dimension': 2,
#  'index_fullness': 0.0,
#  'namespaces': {'ns1': {'vector_count': 3}, 'ns2': {'vector_count': 3}},
#  'total_vector_count': 6}

​

8. Run a similarity search

Query each namespace in your index for the 3 vectors that are most similar to an example 2-dimensional vector using the cosine similarity metric you specified for the index:

query_results1 = index.query(
    namespace="ns1",
    vector=[1.0, 1.5],
    top_k=3,
    include_values=True
)

print(query_results1)

query_results2 = index.query(
    namespace="ns2",
    vector=[1.0,-2.5],
    top_k=3,
    include_values=True
)

print(query_results2)

# Returns:
# {'matches': [{'id': 'vec1', 'score': 1.0, 'values': [1.0, 1.5]},
#              {'id': 'vec2', 'score': 0.868243158, 'values': [2.0, 1.0]},
#              {'id': 'vec3', 'score': 0.850068152, 'values': [0.1, 3.0]}],
#  'namespace': 'ns1',
#  'usage': {'read_units': 6}}
# {'matches': [{'id': 'vec1', 'score': 1.0, 'values': [1.0, -2.5]},
#              {'id': 'vec3', 'score': 0.998274386, 'values': [0.5, -1.5]},
#              {'id': 'vec2', 'score': 0.824041963, 'values': [3.0, -2.0]}],
#  '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.

​

9. Clean up

When you no longer need the “docs-quickstart-index” index, use the delete_index operation to delete it:

pc.delete_index(index_name)

​

Next steps

Check out the following examples and sample apps to see how you can use your serverless index:

• Retrieval augmentation with LangChain
• Semantic search
• Namespace notes sample app
• Upsert your own vector embeddings