Beginner

Setup & Configuration

Create a Pinecone account, install the Python SDK, create your first index, and understand the difference between serverless and pod-based deployments.

Create an Account

  1. Sign up at pinecone.io

    Create a free account. The free tier includes 1 serverless index with up to 2GB of storage.

  2. Get your API key

    Navigate to "API Keys" in the Pinecone console. Copy your default API key for use in the SDK.

Install the Python SDK

Bash 
# Install Pinecone client
pip install pinecone

# With gRPC for better performance (optional)
pip install "pinecone[grpc]"

# Set your API key as environment variable
export PINECONE_API_KEY="your-api-key-here"

Initialize the Client

Python 
from pinecone import Pinecone, ServerlessSpec
import os

# Initialize the Pinecone client
pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

# List existing indexes
print(pc.list_indexes())  # []

Creating an Index

An index is where your vectors live. You need to specify the dimensionality (must match your embedding model) and the distance metric:

Python 
# Create a serverless index (recommended for most use cases)
pc.create_index(
    name="my-index",
    dimension=1536,        # OpenAI text-embedding-3-small
    metric="cosine",       # cosine, euclidean, or dotproduct
    spec=ServerlessSpec(
        cloud="aws",
        region="us-east-1"
    )
)

# Connect to the index
index = pc.Index("my-index")

# Check index stats
print(index.describe_index_stats())
# {'dimension': 1536, 'total_vector_count': 0, ...}

Serverless vs Pod-Based

Feature Serverless Pod-Based
Pricing Pay per read/write/storage Pay per pod-hour
Scaling Automatic Manual (add replicas/pods)
Idle Cost Near zero when idle Pay for running pods
Best For Variable workloads, startups Predictable, high-throughput
Free Tier Yes (generous) No
✅
Dimension matters: The dimension must match your embedding model exactly. OpenAI text-embedding-3-small uses 1536, text-embedding-3-large uses 3072, and Cohere embed-v3 uses 1024. You cannot change the dimension after creation.

Distance Metrics

  • cosine: Best for text embeddings (most common). Measures the angle between vectors, ignoring magnitude.
  • euclidean: Measures straight-line distance. Use when magnitude matters (e.g., image features).
  • dotproduct: Fast computation. Use when vectors are normalized or for recommendation systems.
⚠
Index deletion is permanent: Deleting an index removes all vectors and cannot be undone. Always export or back up important data before deleting indexes.

What's Next?

In the next lesson, we will learn how to upsert vectors into our index, work with metadata, and organize data using namespaces.

← Previous Introduction