/api-vector-db-pinecone

name: api-vector-db-pinecone
description: Pinecone serverless vector database -- index management, vector operations, metadata filtering, namespaces, hybrid search, inference API

Pinecone Patterns

> **Quick Guide:** Use `@pinecone-database/pinecone` (v7.x) for serverless vector database operations. Target indexes by host (`pc.index({ host })`), not by name. Use namespaces for multi-tenant isolation (physically separate, cheaper queries). Batch upserts at 200 records (max 1,000 or 2 MB). Metadata is limited to 40 KB per record with flat key-value pairs only (no nested objects). Pinecone is eventually consistent -- vectors may not appear in queries immediately after upsert. Use `describeIndexStats()` to verify indexing progress. For hybrid search, use `dotproduct` metric with sparse+dense vectors in a single index.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST target indexes by host URL, not by name -- `pc.index({ host })` is the v7 API; `pc.index('name')` is deprecated)**

**(You MUST batch upserts to max 1,000 records or 2 MB per request -- exceeding either limit causes a 400 error)**

**(You MUST use flat key-value metadata only -- nested objects, null values, and keys starting with `$` are rejected by Pinecone)**

**(You MUST handle eventual consistency -- vectors are not queryable immediately after upsert; use `describeIndexStats()` or retry logic for freshness-critical flows)**

</critical_requirements>

---

Examples

• [Core Patterns](examples/core.md) -- Client setup, index creation, upsert, query, fetch, update, delete
• [Namespaces & Multi-Tenancy](examples/namespaces.md) -- Namespace isolation, multi-tenant patterns, namespace management API
• [Metadata Filtering](examples/metadata-filtering.md) -- Filter operators, compound filters, best practices
• [Hybrid Search](examples/hybrid-search.md) -- Sparse-dense vectors, hybrid index setup, alpha weighting
• [Inference API](examples/inference.md) -- Embedding generation, reranking, integrated inference indexes
• [Batch Operations](examples/batch-operations.md) -- Chunked upserts, parallel ingestion, bulk import

**Additional resources:**

• [reference.md](reference.md) -- API quick reference, filter operators, limits, decision frameworks, production checklist

---

**Auto-detection:** Pinecone, @pinecone-database/pinecone, createIndex, createIndexForModel, upsert, query, topK, includeMetadata, sparseValues, namespace, describeIndexStats, vector database, similarity search, embedding, cosine, dotproduct, euclidean, RAG retrieval, semantic search, pinecone-sparse-english, rerank, searchRecords, upsertRecords, fetchByMetadata

**When to use:**

• Semantic search over document embeddings (RAG retrieval)
• Similarity search for recommendations, deduplication, or classification
• Multi-tenant vector isolation using namespaces
• Hybrid semantic + keyword search using sparse-dense vectors
• Embedding generation and result reranking via Pinecone Inference API

**Key patterns covered:**

• Client setup and index management (serverless vs pod-based)
• Vector CRUD operations (upsert, query, fetch, update, delete)
• Metadata filtering with compound operators
• Namespace-based multi-tenancy
• Sparse-dense hybrid search
• Pinecone Inference API (embed, rerank)
• Batch ingestion with chunking and parallelism
• Integrated inference indexes (automatic embedding)

**When NOT to use:**

• Full-text search with complex boolean queries (use a dedicated search engine)
• Relational data with joins and transactions (use a relational database)
• Real-time streaming or pub/sub messaging (use a message broker)
• Storing large binary blobs or documents (use object storage; store only embeddings + metadata references)

---

<philosophy>

Philosophy

Pinecone is a **managed serverless vector database** purpose-built for similarity search at scale. The core principle: **store embeddings and metadata, query by vector similarity, filter by metadata.**

**Core principles:**

1. **Vectors in, results out** -- Pinecone stores high-dimensional vectors and returns the most similar ones. It is not a general-purpose database. Structure your data as embeddings + metadata references. 2. **Namespaces for isolation** -- Use namespaces to physically separate tenant data. Queries scan only the target namespace, reducing cost and latency compared to metadata filtering across a shared namespace. 3. **Metadata is for filtering, not storage** -- Keep metadata small (40 KB limit) and flat. Store document content in your primary database; store only filterable attributes (category, date, tenant ID) as Pinecone metadata. 4. **Batch for throughput** -- Individual upserts are inefficient. Batch at 200 records for optimal throughput (max 1,000 or 2 MB per request). 5. **Eventual consistency is normal** -- Freshly upserted vectors may not appear in query results immediately. Design your application to tolerate brief staleness or poll `describeIndexStats()` before querying.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Client Initialization

Create a Pinecone client from an API key. See [examples/core.md](examples/core.md) for full examples.

// Good Example
import { Pinecone } from "@pinecone-database/pinecone";

function createPineconeClient(): Pinecone {
  const apiKey = process.env.PINECONE_API_KEY;
  if (!apiKey) {
    throw new Error("PINECONE_API_KEY environment variable is required");
  }
  return new Pinecone({ apiKey });
}

export { createPineconeClient };

**Why good:** API key from environment variable, validation before construction, named export

// Bad Example
import { Pinecone } from "@pinecone-database/pinecone";
const pc = new Pinecone({ apiKey: "sk-abc123..." });
// Hardcoded key leaks in version control

**Why bad:** Hardcoded