Creating Serverless Indexes
1. Creating Serverless Index
Example: Python
from pinecone import Pinecone, ServerlessSpec
pc = Pinecone(api_key="...")
pc.create_index(
name="products",
dimension=1536,
metric="cosine",
spec=ServerlessSpec(cloud="aws", region="us-east-1"),
deletion_protection="enabled",
)
Example: Node.js
await pc.createIndex({
name: "products",
dimension: 1536,
metric: "cosine",
spec: { serverless: { cloud: "aws", region: "us-east-1" } },
deletionProtection: "enabled",
});
| Param | Description |
|---|
name | Lowercase, alphanumeric+hyphen, max 45 chars |
dimension | 1–20000; must match embedding model |
metric | cosine | dotproduct | euclidean |
spec | ServerlessSpec with cloud+region |
2. Configuring Cloud Provider
| Cloud | Code | Notes |
|---|
| AWS | "aws" | Most regions, lowest latency for many |
| GCP | "gcp" | Good for GCP-native stacks |
| Azure | "azure" | Limited regions |
3. Selecting Region
| Cloud | Region Codes |
|---|
| AWS | us-east-1, us-west-2, eu-west-1 |
| GCP | us-central1, europe-west4 |
| Azure | eastus2 |
Note: Co-locate Pinecone index with your application servers and embedding API to minimize latency.
4. Setting Index Dimensions
| Rule | Detail |
|---|
| Must match embedding model | 1536 for OpenAI 3-small, 3072 for 3-large |
| Immutable | Cannot change after creation; recreate to alter |
| Range | 1 to 20000 |
5. Configuring Distance Metric
| Metric | When |
|---|
cosine | Default for text embeddings |
dotproduct | Required for hybrid (sparse+dense) |
euclidean | Spatial / image features |
6. Setting Deletion Protection
Example: Toggle Protection
pc.configure_index("products", deletion_protection="enabled")
# To delete later:
pc.configure_index("products", deletion_protection="disabled")
pc.delete_index("products")
| Value | Effect |
|---|
enabled | Blocks delete_index until disabled |
disabled | Allows deletion (default) |
Note: Serverless indexes auto-index all metadata. Selective indexing is a pod-based feature.
| Field Type | Recommendation |
|---|
| High-cardinality strings | Avoid as filter; use for retrieval only |
| Booleans / enums | Ideal for filters |
| Timestamps | Store as UNIX int for range filters |
8. Understanding Auto-Scaling Behavior
| Aspect | Behavior |
|---|
| Read scaling | Auto, based on QPS; no config needed |
| Write scaling | Auto-batched; respects rate limits |
| Storage scaling | Unlimited; billed per GB-month |
| Cold start | ~1–5s after idle period; warm afterward |
9. Monitoring Index Initialization
Example: Wait for Ready
import time
while not pc.describe_index("products").status["ready"]:
time.sleep(1)
print("Index ready")
| Field | Description |
|---|
status.ready | Boolean — true when accepting traffic |
status.state | Initializing, Ready, Terminating |
host | Endpoint URL for index ops |
10. Handling Creation Errors
| Error | Cause | Fix |
|---|
AlreadyExists | Index name conflict | Use different name or describe existing |
Quota | Project index quota hit | Delete unused or upgrade plan |
InvalidDimension | dim < 1 or > 20000 | Use valid dim |
RegionUnavailable | Cloud/region combo not supported | Pick supported region |