Pinecone

What Is Pinecone?

Pinecone is a vector database service built for applications that need fast retrieval over embeddings. Instead of making your application manage a local vector index and its surrounding storage infrastructure, Pinecone provides a database-oriented retrieval layer.

Pinecone vs FAISS and Qdrant

FAISS, Qdrant, and Pinecone can all participate in vector retrieval, but their operating models are different.

Core Pinecone Concepts

How Pinecone Retrieval Works

The application embeds the query, sends the vector to Pinecone, and receives the nearest records. Metadata can then provide the text source, title, URL, category, tenant, or other fields needed by the application.

Python: Connect to Pinecone

The Python SDK uses an API key to authenticate with Pinecone. Keep that key in an environment variable rather than hard-coding it in application code.

import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

for index in pc.list_indexes():
    print(index.name)

Create an Index

An index needs a vector dimension and a similarity metric that match your embedding pipeline. In a serverless setup, you also choose the deployment environment supported by your Pinecone account.

from pinecone import Pinecone, ServerlessSpec
import os

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

index_name = "support-docs"

if not pc.has_index(index_name):
    pc.create_index(
        name=index_name,
        dimension=384,
        metric="cosine",
        spec=ServerlessSpec(
            cloud="aws",
            region="us-east-1",
        ),
    )

print(pc.describe_index(index_name))

Python: Upsert Vectors

Each record can include an ID, vector values, and metadata. Metadata makes search results useful to the rest of your application.

index = pc.Index(index_name)

records = [
    {
        "id": "doc-101",
        "values": [0.10, 0.20, 0.30, 0.40],
        "metadata": {
            "title": "Password Reset",
            "category": "support",
            "language": "en",
        },
    },
    {
        "id": "doc-102",
        "values": [0.80, 0.10, 0.05, 0.20],
        "metadata": {
            "title": "Shipping Policy",
            "category": "commerce",
            "language": "en",
        },
    },
]

index.upsert(vectors=records)

Python: Query Similar Vectors

Send a query vector and request the top matches. Setting include_metadata=True lets the application receive the metadata stored with each result.

query_vector = [0.12, 0.18, 0.28, 0.42]

response = index.query(
    vector=query_vector,
    top_k=3,
    include_metadata=True,
)

for match in response.matches:
    print(match.id, match.score, match.metadata)

Metadata Filtering

Semantic similarity can be combined with structured constraints. For example, a support assistant might retrieve only documents whose category is support.

response = index.query(
    vector=query_vector,
    top_k=3,
    include_metadata=True,
    filter={"category": {"$eq": "support"}},
)

for match in response.matches:
    print(match.metadata["title"], match.score)

Namespaces

Namespaces provide a logical way to separate records inside an index. They can be useful for tenant isolation patterns, environments, departments, or other dataset boundaries.

index.upsert(
    namespace="support-team",
    vectors=records,
)

response = index.query(
    namespace="support-team",
    vector=query_vector,
    top_k=3,
    include_metadata=True,
)

Pinecone in Semantic Search

Pinecone does not decide what the user means from raw text. The embedding model creates the numerical representation; Pinecone retrieves records whose vectors are close according to the configured metric.

Pinecone in RAG

When Pinecone Is a Good Choice

When Pinecone May Not Be the Best Choice

Common Mistakes