# Pinecone -- Batch Operations Examples

> Chunked upserts, parallel ingestion, and bulk data management. See [core.md](core.md) for single-record operations.

**Related examples:**

- [core.md](core.md) -- Basic upsert, query, fetch, delete
- [inference.md](inference.md) -- Batch embedding generation

---

## Shared Utility: Chunk Array

All batch patterns below use this chunking utility.

```typescript
function chunkArray<T>(array: T[], size: number): T[][] {
  const chunks: T[][] = [];
  for (let i = 0; i < array.length; i += size) {
    chunks.push(array.slice(i, i + size));
  }
  return chunks;
}

export { chunkArray };
```

---

## Chunked Sequential Upsert

Batch upserts at 200 records to stay well within the 1,000-record / 2 MB limit.

```typescript
import type { Pinecone, RecordMetadata } from "@pinecone-database/pinecone";

const UPSERT_BATCH_SIZE = 200;

interface VectorRecord<T extends RecordMetadata = RecordMetadata> {
  id: string;
  values: number[];
  metadata?: T;
}

async function batchUpsert<T extends RecordMetadata>(
  index: ReturnType<Pinecone["index"]>,
  namespace: string,
  records: VectorRecord<T>[],
): Promise<void> {
  const batches = chunkArray(records, UPSERT_BATCH_SIZE);
  const ns = index.namespace(namespace);

  for (const batch of batches) {
    await ns.upsert({ records: batch });
  }
}

export { batchUpsert };
```

**Why good:** Named constant for batch size, generic metadata type, sequential processing avoids overwhelming the API

---

## Parallel Upsert with Concurrency Control

For large datasets, parallel upserts increase throughput while respecting rate limits.

```typescript
import type { Pinecone, RecordMetadata } from "@pinecone-database/pinecone";

const UPSERT_BATCH_SIZE = 200;
const MAX_CONCURRENT_UPSERTS = 5;

async function parallelBatchUpsert<T extends RecordMetadata>(
  index: ReturnType<Pinecone["index"]>,
  namespace: string,
  records: Array<{ id: string; values: number[]; metadata?: T }>,
): Promise<void> {
  const batches = chunkArray(records, UPSERT_BATCH_SIZE);
  const ns = index.namespace(namespace);

  // Process batches with bounded concurrency
  for (let i = 0; i < batches.length; i += MAX_CONCURRENT_UPSERTS) {
    const concurrentBatches = batches.slice(i, i + MAX_CONCURRENT_UPSERTS);
    await Promise.all(
      concurrentBatches.map((batch) => ns.upsert({ records: batch })),
    );
  }
}

export { parallelBatchUpsert };
```

**Why good:** Bounded concurrency prevents rate limiting, `Promise.all` for parallel execution within each window, sequential windows prevent overload

---

## Batch Upsert with Progress Tracking

```typescript
import type { Pinecone, RecordMetadata } from "@pinecone-database/pinecone";

const UPSERT_BATCH_SIZE = 200;

async function batchUpsertWithProgress<T extends RecordMetadata>(
  index: ReturnType<Pinecone["index"]>,
  namespace: string,
  records: Array<{ id: string; values: number[]; metadata?: T }>,
  onProgress?: (completed: number, total: number) => void,
): Promise<void> {
  const batches = chunkArray(records, UPSERT_BATCH_SIZE);
  const ns = index.namespace(namespace);
  let completed = 0;

  for (const batch of batches) {
    await ns.upsert({ records: batch });
    completed += batch.length;
    onProgress?.(completed, records.length);
  }
}

export { batchUpsertWithProgress };
```

**Why good:** Progress callback for long-running ingestion jobs, accurate count tracking

---

## Batch Upsert with Retry Logic

```typescript
import type { Pinecone, RecordMetadata } from "@pinecone-database/pinecone";

const UPSERT_BATCH_SIZE = 200;
const MAX_RETRIES = 3;
const INITIAL_BACKOFF_MS = 1000;

async function upsertWithRetry<T extends RecordMetadata>(
  ns: ReturnType<Pinecone["index"]>,
  records: Array<{ id: string; values: number[]; metadata?: T }>,
): Promise<void> {
  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
    try {
      await ns.upsert({ records });
      return;
    } catch (error) {
      const isRetryable =
        error instanceof Error &&
        (error.message.includes("429") || error.message.includes("503"));

      if (!isRetryable || attempt === MAX_RETRIES - 1) {
        throw error;
      }

      const backoffMs = INITIAL_BACKOFF_MS * Math.pow(2, attempt);
      await new Promise((resolve) => setTimeout(resolve, backoffMs));
    }
  }
}

async function batchUpsertWithRetry<T extends RecordMetadata>(
  index: ReturnType<Pinecone["index"]>,
  namespace: string,
  records: Array<{ id: string; values: number[]; metadata?: T }>,
): Promise<void> {
  const batches = chunkArray(records, UPSERT_BATCH_SIZE);
  const ns = index.namespace(namespace);

  for (const batch of batches) {
    await upsertWithRetry(ns, batch);
  }
}

export { batchUpsertWithRetry };
```

**Why good:** Exponential backoff for rate limits (429) and server errors (503), named constants, non-retryable errors propagate immediately

---

## Verify Upsert Completion

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const POLL_INTERVAL_MS = 2000;
const MAX_POLL_ATTEMPTS = 30;

async function waitForUpsertCompletion(
  index: ReturnType<Pinecone["index"]>,
  expectedCount: number,
  namespace?: string,
): Promise<boolean> {
  for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
    const stats = await index.describeIndexStats();

    const currentCount = namespace
      ? (stats.namespaces?.[namespace]?.recordCount ?? 0)
      : (stats.totalRecordCount ?? 0);

    if (currentCount >= expectedCount) {
      return true;
    }

    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
  }

  return false; // Timed out waiting for vectors to be indexed
}

export { waitForUpsertCompletion };
```

**Why good:** Handles eventual consistency by polling, namespace-aware count check, timeout prevents infinite waiting

**Gotcha:** `describeIndexStats()` counts are approximate. For exact verification, query for a specific recently-upserted ID using `fetch`.

---

## Batch Delete by IDs

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const DELETE_BATCH_SIZE = 1000; // Max IDs per deleteMany call

async function batchDelete(
  index: ReturnType<Pinecone["index"]>,
  namespace: string,
  ids: string[],
): Promise<void> {
  const ns = index.namespace(namespace);
  const batches = chunkArray(ids, DELETE_BATCH_SIZE);

  for (const batch of batches) {
    await ns.deleteMany({ ids: batch });
  }
}

export { batchDelete };
```

**Why good:** Respects 1,000 ID limit per delete request, sequential batching

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Pinecone -- Core Pattern Examples

> Client setup, index management, and fundamental vector operations (upsert, query, fetch, update, delete). Reference from [SKILL.md](../SKILL.md).

**Related examples:**

- [namespaces.md](namespaces.md) -- Namespace isolation, multi-tenant patterns
- [metadata-filtering.md](metadata-filtering.md) -- Filter operators and compound filters
- [hybrid-search.md](hybrid-search.md) -- Sparse-dense hybrid search
- [inference.md](inference.md) -- Embedding generation and reranking
- [batch-operations.md](batch-operations.md) -- Chunked upserts, parallel ingestion

---

## Client Initialization

```typescript
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 (never hardcoded), explicit validation, named export

The `Pinecone` constructor also reads `PINECONE_API_KEY` from the environment automatically if no `apiKey` is passed. Explicit passing is preferred for clarity and to fail fast with a clear error.

---

## Create a Serverless Index

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

const EMBEDDING_DIMENSION = 1536; // Must match your embedding model
const INDEX_NAME = "documents";

async function createServerlessIndex(pc: Pinecone): Promise<string> {
  const indexModel = await pc.createIndex({
    name: INDEX_NAME,
    dimension: EMBEDDING_DIMENSION,
    metric: "cosine",
    spec: {
      serverless: {
        cloud: "aws",
        region: "us-east-1",
      },
    },
    waitUntilReady: true, // Block until index is ready for operations
  });

  return indexModel.host; // Save this -- use it to target the index
}

export { createServerlessIndex };
```

**Why good:** Named constants for dimension and name, `waitUntilReady: true` prevents premature operations, returns host URL for index targeting

```typescript
// ❌ Bad Example -- wrong dimension, no wait
const indexModel = await pc.createIndex({
  name: "docs",
  dimension: 768, // Mismatch if using a 1536-dim model
  metric: "cosine",
  spec: { serverless: { cloud: "aws", region: "us-east-1" } },
});
// Index may not be ready yet -- operations will fail
const index = pc.index({ host: indexModel.host });
await index.upsert({ records: [...] }); // May throw
```

**Why bad:** Dimension mismatch causes 400 errors on upsert, no `waitUntilReady` means index may not accept operations immediately

---

## Target an Index by Host

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

// v7 API -- target by host (preferred)
const INDEX_HOST = process.env.PINECONE_INDEX_HOST;

function getIndex(pc: Pinecone): ReturnType<Pinecone["index"]> {
  if (!INDEX_HOST) {
    throw new Error("PINECONE_INDEX_HOST environment variable is required");
  }
  return pc.index({ host: INDEX_HOST });
}

export { getIndex };
```

**Why good:** Host URL from environment, avoids extra API call to resolve name to host

If you don't have the host URL stored, use `describeIndex` to retrieve it:

```typescript
const indexModel = await pc.describeIndex(INDEX_NAME);
const index = pc.index({ host: indexModel.host });
```

---

## Upsert Vectors with Typed Metadata

```typescript
import type { Pinecone, RecordMetadata } from "@pinecone-database/pinecone";

interface ArticleMetadata extends RecordMetadata {
  title: string;
  category: string;
  publishedAt: number; // Unix timestamp
  tags: string[]; // Only string arrays are supported
}

const NAMESPACE = "articles";

async function upsertArticle(
  index: ReturnType<Pinecone["index"]>,
  id: string,
  embedding: number[],
  metadata: ArticleMetadata,
): Promise<void> {
  await index.namespace(NAMESPACE).upsert({
    records: [{ id, values: embedding, metadata }],
  });
}

export { upsertArticle };
export type { ArticleMetadata };
```

**Why good:** Type-safe metadata via `RecordMetadata` extension, namespace isolation, Unix timestamp for dates (not Date objects), string array for tags

```typescript
// ❌ Bad Example -- invalid metadata
await index.upsert({
  records: [
    {
      id: "doc-1",
      values: embedding,
      metadata: {
        title: "Guide",
        author: { name: "Alice", role: "admin" }, // INVALID: nested object
        createdAt: new Date(), // INVALID: Date object
        $priority: "high", // INVALID: key starts with $
        score: null, // INVALID: null value
      },
    },
  ],
});
```

**Why bad:** Nested objects are not supported, Date objects are not serializable, `$`-prefixed keys are reserved for operators, null values are rejected

---

## Query by Vector Similarity

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";
import type { ArticleMetadata } from "./upsert-article";

const TOP_K = 10;
const NAMESPACE = "articles";

interface SearchResult {
  id: string;
  score: number;
  metadata: ArticleMetadata | undefined;
}

async function searchArticles(
  index: ReturnType<Pinecone["index"]>,
  queryEmbedding: number[],
  category?: string,
): Promise<SearchResult[]> {
  const filter = category ? { category: { $eq: category } } : undefined;

  const response = await index.namespace(NAMESPACE).query({
    vector: queryEmbedding,
    topK: TOP_K,
    includeMetadata: true,
    filter,
  });

  return response.matches.map((match) => ({
    id: match.id,
    score: match.score ?? 0,
    metadata: match.metadata as ArticleMetadata | undefined,
  }));
}

export { searchArticles };
```

**Why good:** Optional filter, `includeMetadata: true` to get metadata back, typed response mapping, named constant for topK

---

## Fetch Vectors by ID

```typescript
const NAMESPACE = "articles";

async function fetchArticles(
  index: ReturnType<Pinecone["index"]>,
  ids: string[],
): Promise<void> {
  // Max 1,000 IDs per fetch
  const response = await index.namespace(NAMESPACE).fetch({ ids });

  for (const [id, record] of Object.entries(response.records)) {
    console.log(id, record.metadata);
    // record.values contains the vector (if stored)
  }
}

export { fetchArticles };
```

**Why good:** Targets namespace, respects 1,000 ID limit, iterates response records correctly

**Gotcha:** `fetch` returns an object keyed by ID, not an array. Missing IDs are silently omitted from the response (no error thrown).

---

## Update Vector Metadata

```typescript
const NAMESPACE = "articles";

async function updateArticleCategory(
  index: ReturnType<Pinecone["index"]>,
  id: string,
  newCategory: string,
): Promise<void> {
  await index.namespace(NAMESPACE).update({
    id,
    metadata: { category: newCategory },
    // Only specified fields are updated -- other metadata fields are preserved
  });
}

export { updateArticleCategory };
```

**Why good:** Partial metadata update (only `category` changes, other fields preserved), targets namespace

**Gotcha:** `update()` merges metadata fields, it does not replace the entire metadata object. To remove a metadata field, you must re-upsert the entire record.

---

## Delete Vectors

```typescript
const NAMESPACE = "articles";

// Delete by IDs
async function deleteArticles(
  index: ReturnType<Pinecone["index"]>,
  ids: string[],
): Promise<void> {
  await index.namespace(NAMESPACE).deleteMany({ ids });
}

// Delete by metadata filter
async function deleteByCategory(
  index: ReturnType<Pinecone["index"]>,
  category: string,
): Promise<void> {
  await index.namespace(NAMESPACE).deleteMany({
    filter: { category: { $eq: category } },
  });
}

// Delete all vectors in a namespace
async function clearNamespace(
  index: ReturnType<Pinecone["index"]>,
): Promise<void> {
  await index.namespace(NAMESPACE).deleteAll();
}

export { deleteArticles, deleteByCategory, clearNamespace };
```

**Why good:** Three deletion patterns (by ID, by filter, all), targets namespace, named exports

**Gotcha:** `deleteAll()` without a namespace targets the default (empty) namespace. To delete everything across all namespaces, you must delete each namespace individually or delete and recreate the index.

---

## Check Index Statistics

```typescript
async function getIndexStats(
  index: ReturnType<Pinecone["index"]>,
): Promise<void> {
  const stats = await index.describeIndexStats();

  console.log("Total vectors:", stats.totalRecordCount);
  console.log("Index fullness:", stats.indexFullness);
  console.log("Dimension:", stats.dimension);

  // Per-namespace breakdown
  if (stats.namespaces) {
    for (const [ns, nsStats] of Object.entries(stats.namespaces)) {
      console.log(`  Namespace "${ns}": ${nsStats.recordCount} vectors`);
    }
  }
}

export { getIndexStats };
```

**Why good:** Shows total and per-namespace counts, useful for monitoring and verifying upsert completion

**Gotcha:** Record counts from `describeIndexStats()` are approximate and may lag behind recent upserts by several seconds.

---

## List Vector IDs with Pagination

```typescript
const PAGE_SIZE = 100;
const NAMESPACE = "articles";

async function listAllVectorIds(
  index: ReturnType<Pinecone["index"]>,
): Promise<string[]> {
  const allIds: string[] = [];
  let paginationToken: string | undefined;

  do {
    const response = await index.namespace(NAMESPACE).listPaginated({
      limit: PAGE_SIZE,
      paginationToken,
      prefix: "doc-", // Optional: filter by ID prefix
    });

    if (response.vectors) {
      allIds.push(...response.vectors.map((v) => v.id));
    }
    paginationToken = response.pagination?.next;
  } while (paginationToken);

  return allIds;
}

export { listAllVectorIds };
```

**Why good:** Handles pagination correctly, optional prefix filter, collects all IDs across pages

**Gotcha:** `listPaginated` returns only vector IDs, not values or metadata. Use `fetch` to get full vector data for specific IDs.

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Pinecone -- Hybrid Search Examples

> Sparse-dense hybrid search combining semantic and keyword retrieval. See [core.md](core.md) for basic query patterns and [inference.md](inference.md) for embedding generation.

**Related examples:**

- [core.md](core.md) -- Basic vector operations
- [inference.md](inference.md) -- Sparse embedding generation with `pinecone-sparse-english-v0`

---

## Create a Hybrid Index

Hybrid search requires `dotproduct` metric -- the only metric that supports combined sparse+dense queries.

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

const DENSE_DIMENSION = 1536;
const HYBRID_INDEX_NAME = "hybrid-search";

async function createHybridIndex(pc: Pinecone): Promise<string> {
  const indexModel = await pc.createIndex({
    name: HYBRID_INDEX_NAME,
    dimension: DENSE_DIMENSION,
    metric: "dotproduct", // REQUIRED for hybrid search
    spec: {
      serverless: {
        cloud: "aws",
        region: "us-east-1",
      },
    },
    waitUntilReady: true,
  });

  return indexModel.host;
}

export { createHybridIndex };
```

**Why good:** Uses `dotproduct` metric (required for sparse-dense), `waitUntilReady` prevents premature operations

```typescript
// ❌ Bad Example -- wrong metric for hybrid
await pc.createIndex({
  name: "hybrid",
  dimension: 1536,
  metric: "cosine", // Does NOT support sparse-dense queries
  spec: { serverless: { cloud: "aws", region: "us-east-1" } },
});
```

**Why bad:** `cosine` and `euclidean` metrics do not support sparse vector queries; only `dotproduct` works for hybrid search

---

## Upsert with Sparse + Dense Vectors

Each record can have both `values` (dense) and `sparseValues` (sparse).

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const NAMESPACE = "documents";

interface SparseVector {
  indices: number[]; // uint32 positive integers
  values: number[]; // Non-zero floats
}

async function upsertHybridRecord(
  index: ReturnType<Pinecone["index"]>,
  id: string,
  denseEmbedding: number[],
  sparseEmbedding: SparseVector,
  metadata: Record<string, string | number>,
): Promise<void> {
  await index.namespace(NAMESPACE).upsert({
    records: [
      {
        id,
        values: denseEmbedding,
        sparseValues: sparseEmbedding,
        metadata,
      },
    ],
  });
}

export { upsertHybridRecord };
export type { SparseVector };
```

**Why good:** Both dense and sparse vectors on the same record, typed sparse vector interface, metadata included

**Gotcha:** Sparse vector `indices` must be positive 32-bit integers and `values` must be non-zero floats. Zero values are silently dropped.

---

## Hybrid Query with Alpha Weighting

Control the balance between semantic (dense) and keyword (sparse) relevance using alpha weighting.

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";
import type { SparseVector } from "./upsert-hybrid";

const TOP_K = 10;
const NAMESPACE = "documents";

function scaleVector(vector: number[], alpha: number): number[] {
  return vector.map((v) => v * alpha);
}

function scaleSparseVector(sparse: SparseVector, alpha: number): SparseVector {
  return {
    indices: sparse.indices,
    values: sparse.values.map((v) => v * alpha),
  };
}

async function hybridSearch(
  index: ReturnType<Pinecone["index"]>,
  denseQuery: number[],
  sparseQuery: SparseVector,
  alpha: number = 0.7, // 0 = pure keyword, 1 = pure semantic
): Promise<void> {
  const results = await index.namespace(NAMESPACE).query({
    vector: scaleVector(denseQuery, alpha),
    sparseVector: scaleSparseVector(sparseQuery, 1 - alpha),
    topK: TOP_K,
    includeMetadata: true,
  });

  for (const match of results.matches) {
    console.log(match.id, match.score, match.metadata);
  }
}

export { hybridSearch };
```

**Why good:** Alpha weighting controls semantic vs keyword balance, scaling applied before query, pure semantic (alpha=1) or pure keyword (alpha=0) modes available

**Note:** Alpha tuning is domain-specific. Start at 0.7 (70% semantic, 30% keyword) and adjust based on relevance evaluation.

---

## Generate Sparse Embeddings via Inference API

Use Pinecone's hosted sparse model for keyword-style embeddings.

```typescript
import { Pinecone } from "@pinecone-database/pinecone";
import type { SparseVector } from "./upsert-hybrid";

async function generateSparseEmbedding(
  pc: Pinecone,
  text: string,
  inputType: "passage" | "query",
): Promise<SparseVector> {
  const result = await pc.inference.embed({
    model: "pinecone-sparse-english-v0",
    inputs: [{ text }],
    parameters: { inputType, truncate: "END" },
  });

  const embedding = result.data[0];
  if (!embedding.sparseValues) {
    throw new Error("Sparse model did not return sparse values");
  }

  return {
    indices: embedding.sparseValues.indices,
    values: embedding.sparseValues.values,
  };
}

export { generateSparseEmbedding };
```

**Why good:** Uses `inputType` to distinguish passage indexing from query time, `truncate: "END"` handles long inputs

**Important:** Use `inputType: "passage"` when generating embeddings for upsert and `inputType: "query"` when generating embeddings for search. Using the wrong type degrades relevance.

---

## Limitations of Single Hybrid Index

```
Hybrid index (dotproduct metric):
  ✅ Combined sparse + dense queries
  ✅ Alpha weighting for relevance tuning
  ❌ Cannot do sparse-only queries
  ❌ Cannot use integrated embedding (createIndexForModel)
  ❌ Cannot use searchRecords or upsertRecords convenience methods

Separate dense index (cosine metric):
  ✅ Integrated inference (automatic embedding)
  ✅ searchRecords / upsertRecords
  ❌ No sparse vector support
  ❌ No hybrid queries
```

**When to choose hybrid:** You need combined semantic + keyword search and are willing to manage your own embedding pipeline.

**When to skip hybrid:** Pure semantic search is sufficient, and you want the simplest architecture with integrated inference.

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Pinecone -- Inference API Examples

> Embedding generation, reranking, and integrated inference indexes. See [core.md](core.md) for basic operations and [hybrid-search.md](hybrid-search.md) for sparse embeddings.

**Related examples:**

- [core.md](core.md) -- Client setup, upsert, query
- [hybrid-search.md](hybrid-search.md) -- Sparse embeddings for hybrid search
- [batch-operations.md](batch-operations.md) -- Batch embedding generation

---

## Generate Dense Embeddings

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

async function embedTexts(
  pc: Pinecone,
  texts: string[],
  inputType: "passage" | "query",
): Promise<number[][]> {
  const result = await pc.inference.embed({
    model: "multilingual-e5-large",
    inputs: texts.map((text) => ({ text })),
    parameters: {
      inputType, // "passage" for indexing, "query" for search
      truncate: "END", // Truncate if input exceeds model's context window
    },
  });

  return result.data.map((item) => {
    if (!item.values) {
      throw new Error("Embedding model did not return dense values");
    }
    return item.values;
  });
}

export { embedTexts };
```

**Why good:** `inputType` distinguishes indexing from querying (critical for asymmetric models), `truncate` handles long inputs gracefully, validates return values

**Important:** Always use `inputType: "passage"` when generating embeddings for documents being indexed, and `inputType: "query"` for search queries. Mixing these up degrades retrieval quality with asymmetric models.

---

## Rerank Query Results

Reranking improves relevance by scoring query-document pairs with a cross-encoder model, which is more accurate than vector similarity alone.

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const RERANK_TOP_N = 5;

interface RankedResult {
  id: string;
  text: string;
  relevanceScore: number;
}

async function rerankResults(
  pc: Pinecone,
  query: string,
  documents: Array<{ id: string; text: string }>,
): Promise<RankedResult[]> {
  const result = await pc.inference.rerank({
    model: "pinecone-rerank-v0",
    query,
    documents,
    topN: RERANK_TOP_N,
    returnDocuments: true,
    rankFields: ["text"],
  });

  return result.data.map((item) => ({
    id: item.document?.id ?? "",
    text: item.document?.text ?? "",
    relevanceScore: item.score,
  }));
}

export { rerankResults };
```

**Why good:** `topN` limits output, `returnDocuments: true` includes document content in response, `rankFields` specifies which fields to rank on, typed return value

**Pattern:** First query Pinecone for top-K candidates (e.g., 50), then rerank to get the most relevant top-N (e.g., 5). This two-stage approach balances recall and precision.

---

## Two-Stage Retrieval: Query + Rerank

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const INITIAL_TOP_K = 50; // Broad retrieval
const RERANK_TOP_N = 5; // Precise reranking

async function searchAndRerank(
  pc: Pinecone,
  index: ReturnType<Pinecone["index"]>,
  queryEmbedding: number[],
  queryText: string,
  namespace: string,
) {
  // Stage 1: Broad vector search
  const candidates = await index.namespace(namespace).query({
    vector: queryEmbedding,
    topK: INITIAL_TOP_K,
    includeMetadata: true,
  });

  if (candidates.matches.length === 0) {
    return [];
  }

  // Stage 2: Rerank with cross-encoder
  const documents = candidates.matches.map((m) => ({
    id: m.id,
    text: (m.metadata?.content as string) ?? "",
  }));

  const reranked = await pc.inference.rerank({
    model: "pinecone-rerank-v0",
    query: queryText,
    documents,
    topN: RERANK_TOP_N,
    returnDocuments: true,
    rankFields: ["text"],
  });

  return reranked.data.map((item) => ({
    id: item.document?.id ?? "",
    text: item.document?.text ?? "",
    score: item.score,
  }));
}

export { searchAndRerank };
```

**Why good:** Two-stage retrieval (broad recall then precise reranking), named constants for K and N, handles empty results

---

## Integrated Inference Index

Create an index that automatically generates embeddings on upsert and query -- no external embedding pipeline needed.

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

const INDEX_NAME = "auto-embed";
const TEXT_FIELD = "chunk_text";

async function createIntegratedIndex(pc: Pinecone): Promise<string> {
  const indexModel = await pc.createIndexForModel({
    name: INDEX_NAME,
    cloud: "aws",
    region: "us-east-1",
    embed: {
      model: "multilingual-e5-large",
      fieldMap: { text: TEXT_FIELD }, // Which metadata field to embed
    },
  });

  return indexModel.host;
}

export { createIntegratedIndex };
```

**Why good:** Pinecone handles embedding automatically, `fieldMap` maps the text source field, no dimension/metric config needed (derived from model)

---

## Upsert and Search with Integrated Inference

With an integrated inference index, you upsert text records and search with text queries -- no vectors involved.

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const NAMESPACE = "articles";
const TOP_K = 10;

// Upsert raw text -- Pinecone generates embeddings automatically
async function upsertTextRecords(
  index: ReturnType<Pinecone["index"]>,
  records: Array<{ id: string; chunkText: string; category: string }>,
): Promise<void> {
  // upsertRecords takes a direct array, not { records: [...] }
  // _id is the canonical field; id also works as an alias
  await index.namespace(NAMESPACE).upsertRecords(
    records.map((r) => ({
      _id: r.id,
      chunk_text: r.chunkText, // Must match fieldMap.text from index creation
      category: r.category,
    })),
  );
}

// Search with text query -- Pinecone embeds the query automatically
async function searchByText(
  index: ReturnType<Pinecone["index"]>,
  queryText: string,
): Promise<void> {
  const results = await index.namespace(NAMESPACE).searchRecords({
    query: { topK: TOP_K, inputs: { text: queryText } },
  });

  for (const hit of results.result.hits) {
    console.log(hit._id, hit._score, hit.fields);
  }
}

export { upsertTextRecords, searchByText };
```

**Why good:** No vector generation code needed, `_id` identifies records (`id` also works as an alias), `upsertRecords` takes a direct array (not `{ records: [...] }`), search uses text input directly

**Gotcha:** Integrated inference indexes use different method names (`upsertRecords`/`searchRecords` instead of `upsert`/`query`), different record shapes (`_id` with metadata fields as top-level properties), and `upsertRecords` accepts a max of 96 records per call (not 1,000 like `upsert`).

---

## List Available Models

```typescript
import { Pinecone } from "@pinecone-database/pinecone";

async function listEmbeddingModels(pc: Pinecone): Promise<void> {
  const models = await pc.inference.listModels({
    type: "embed", // Filter to embedding models only
  });

  for (const model of models.models ?? []) {
    console.log(
      `${model.model}: ${model.vectorType}, dim=${model.defaultDimension}`,
    );
  }
}

export { listEmbeddingModels };
```

**Why good:** Filtered by model type, shows key properties (vector type, dimension)

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Pinecone -- Metadata Filtering Examples

> Filter operators, compound filters, and best practices. See [core.md](core.md) for basic query patterns and [reference.md](../reference.md) for the operator table.

**Related examples:**

- [core.md](core.md) -- Client setup, basic query with filters
- [namespaces.md](namespaces.md) -- Alternative to filtering for multi-tenancy

---

## Comparison Operators

```typescript
const TOP_K = 10;

// Exact match
const drama = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { genre: { $eq: "drama" } },
});

// Not equal
const notComedy = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { genre: { $ne: "comedy" } },
});

// Numeric range
const recent = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { year: { $gte: 2020 } },
});

// Set membership
const selected = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { genre: { $in: ["drama", "action", "thriller"] } },
});
```

**Why good:** Each operator targets specific types (see reference.md for full operator table), `$in` for set membership avoids multiple `$or` clauses

---

## Compound Filters with $and / $or

Only `$and` and `$or` are allowed at the top level of a filter expression.

```typescript
const TOP_K = 10;

// AND: all conditions must match
const filteredResults = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: {
    $and: [
      { genre: { $eq: "drama" } },
      { year: { $gte: 2020 } },
      { rating: { $gt: 7.5 } },
    ],
  },
});

// OR: any condition matches
const broadResults = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: {
    $or: [{ genre: { $eq: "drama" } }, { genre: { $eq: "documentary" } }],
  },
});

// Combined AND + OR
const complexResults = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: {
    $and: [
      { year: { $gte: 2020 } },
      {
        $or: [{ genre: { $eq: "drama" } }, { genre: { $eq: "thriller" } }],
      },
    ],
  },
});
```

**Why good:** Nested logical operators for complex queries, `$or` inside `$and` for flexible filtering

---

## Field Existence Check

```typescript
const TOP_K = 10;

// Only records that have a "summary" field
const withSummary = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { summary: { $exists: true } },
});

// Records missing a "category" field
const uncategorized = await index.namespace(ns).query({
  vector: embedding,
  topK: TOP_K,
  includeMetadata: true,
  filter: { category: { $exists: false } },
});
```

**Why good:** `$exists` checks for field presence without requiring a specific value, useful for incremental data enrichment workflows

---

## Delete by Metadata Filter

```typescript
// Delete all records matching a filter
await index.namespace(ns).deleteMany({
  filter: {
    $and: [{ status: { $eq: "archived" } }, { createdAt: { $lt: 1700000000 } }],
  },
});
```

**Why good:** Bulk deletion without knowing vector IDs, combines metadata filter with namespace targeting

---

## Fetch by Metadata Filter

```typescript
// Fetch records by metadata (no vector required)
const response = await index.namespace(ns).fetchByMetadata({
  filter: { category: { $eq: "tutorial" } },
  limit: 50,
});

for (const record of response.records ?? []) {
  console.log(record.id, record.metadata);
}
```

**Why good:** Retrieves records by metadata without needing vector IDs or a query vector, useful for data management tasks

---

## Common Filter Mistakes

```typescript
// ❌ Bad: Array as filter value (not valid syntax)
filter: { genre: ["drama", "action"] }
// Fix: use $in operator
filter: { genre: { $in: ["drama", "action"] } }

// ❌ Bad: Nested object in metadata
metadata: { author: { name: "Alice", org: "Acme" } }
// Fix: flatten to top-level keys
metadata: { authorName: "Alice", authorOrg: "Acme" }

// ❌ Bad: $eq with array value
filter: { genre: { $eq: ["drama", "action"] } }
// Fix: use $in for set membership
filter: { genre: { $in: ["drama", "action"] } }

// ❌ Bad: Type mismatch in comparison
// Metadata: { year: 2024 } (number)
filter: { year: { $eq: "2024" } } // String "2024" does NOT match number 2024
// Fix: use matching type
filter: { year: { $eq: 2024 } }

// ❌ Bad: Null value in metadata
metadata: { category: null }
// Fix: omit the field entirely, or use a sentinel value
metadata: { category: "uncategorized" }
```

**Why bad:** Each mistake causes either a rejection or silently empty results; type-strict comparisons are a common source of "no results" bugs

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_

# Pinecone -- Namespaces & Multi-Tenancy Examples

> Namespace isolation patterns for multi-tenant applications. See [core.md](core.md) for basic vector operations.

**Related examples:**

- [core.md](core.md) -- Client setup, upsert, query, fetch, update, delete
- [metadata-filtering.md](metadata-filtering.md) -- Filter operators (alternative to namespace isolation)

---

## Namespace-Based Tenant Isolation

Namespaces physically separate data within an index. Queries scan only the target namespace, making them cheaper and faster than metadata filtering at scale.

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const TOP_K = 10;

function getTenantIndex(pc: Pinecone, host: string, tenantId: string) {
  return pc.index({ host }).namespace(`tenant-${tenantId}`);
}

async function searchTenant(
  pc: Pinecone,
  host: string,
  tenantId: string,
  queryEmbedding: number[],
) {
  const ns = getTenantIndex(pc, host, tenantId);

  const results = await ns.query({
    vector: queryEmbedding,
    topK: TOP_K,
    includeMetadata: true,
  });

  return results.matches;
}

export { getTenantIndex, searchTenant };
```

**Why good:** Physical isolation per tenant, query cost proportional to tenant data size (not total index size), simple namespace naming convention

---

## Namespace Management API

The v7 SDK provides explicit namespace management methods.

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const INDEX_HOST = process.env.PINECONE_INDEX_HOST!;

async function setupTenantNamespace(
  pc: Pinecone,
  tenantId: string,
): Promise<void> {
  const index = pc.index({ host: INDEX_HOST });
  const namespaceName = `tenant-${tenantId}`;

  // Create namespace (v7 API -- explicit creation)
  await index.createNamespace({
    name: namespaceName,
    // Optional: declare metadata schema for this namespace
  });
}

async function removeTenantNamespace(
  pc: Pinecone,
  tenantId: string,
): Promise<void> {
  const index = pc.index({ host: INDEX_HOST });
  // Deletes namespace and ALL vectors within it
  await index.deleteNamespace(`tenant-${tenantId}`);
}

async function listTenantNamespaces(pc: Pinecone): Promise<string[]> {
  const index = pc.index({ host: INDEX_HOST });
  const response = await index.listNamespaces({
    prefix: "tenant-", // Filter by prefix
  });

  return response.namespaces?.map((ns) => ns.name) ?? [];
}

export { setupTenantNamespace, removeTenantNamespace, listTenantNamespaces };
```

**Why good:** Explicit namespace lifecycle management, prefix-based listing for tenant discovery, `deleteNamespace` cleanly removes tenant data

---

## Tenant Onboarding and Offboarding

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

interface TenantData {
  id: string;
  documents: Array<{
    id: string;
    embedding: number[];
    metadata: Record<string, string | number>;
  }>;
}

const INDEX_HOST = process.env.PINECONE_INDEX_HOST!;
const UPSERT_BATCH_SIZE = 200;

async function onboardTenant(pc: Pinecone, tenant: TenantData): Promise<void> {
  const ns = pc.index({ host: INDEX_HOST }).namespace(`tenant-${tenant.id}`);

  // Batch upsert tenant documents
  for (let i = 0; i < tenant.documents.length; i += UPSERT_BATCH_SIZE) {
    const batch = tenant.documents.slice(i, i + UPSERT_BATCH_SIZE);
    await ns.upsert({
      records: batch.map((doc) => ({
        id: doc.id,
        values: doc.embedding,
        metadata: doc.metadata,
      })),
    });
  }
}

async function offboardTenant(pc: Pinecone, tenantId: string): Promise<void> {
  const index = pc.index({ host: INDEX_HOST });
  // Single call removes all tenant data
  await index.deleteNamespace(`tenant-${tenantId}`);
}

export { onboardTenant, offboardTenant };
```

**Why good:** Batched upserts during onboarding, single-call offboarding via `deleteNamespace`, clean data isolation

---

## Per-Namespace Statistics

```typescript
import type { Pinecone } from "@pinecone-database/pinecone";

const INDEX_HOST = process.env.PINECONE_INDEX_HOST!;

async function getTenantStats(
  pc: Pinecone,
  tenantId: string,
): Promise<{ recordCount: number }> {
  const index = pc.index({ host: INDEX_HOST });
  const stats = await index.describeIndexStats();

  const nsName = `tenant-${tenantId}`;
  const nsStats = stats.namespaces?.[nsName];

  if (!nsStats) {
    return { recordCount: 0 };
  }

  return { recordCount: nsStats.recordCount ?? 0 };
}

export { getTenantStats };
```

**Why good:** Per-namespace vector count, handles missing namespace gracefully

**Gotcha:** `describeIndexStats()` returns approximate counts. For exact counts after bulk operations, allow a few seconds for indexing to complete.

---

## Namespace vs Metadata Filtering -- Cost Comparison

```
Scenario: 100 tenants, 1 GB data each, querying one tenant

Namespace approach:
  Query scans: 1 GB (tenant's namespace only)
  Cost: ~1 read unit per query

Metadata filtering approach (single namespace):
  Query scans: 100 GB (entire namespace, then filters)
  Cost: ~100 read units per query

At 1,000 queries/day: namespace approach is 100x cheaper.
```

**Rule of thumb:** Use namespaces for multi-tenancy when you have more than a handful of tenants or when total data exceeds a few GB. Use metadata filtering only when you need cross-tenant queries.

---

_Full skill documentation: [SKILL.md](../SKILL.md) | Quick reference: [reference.md](../reference.md)_