Pinecone Plugin

The genkitx-pinecone plugin provides integration with Pinecone, a managed vector database optimized for production AI applications. Use it for high-performance retrieval-augmented generation (RAG) and semantic search at scale.

Installation

npm install genkitx-pinecone @pinecone-database/pinecone

Prerequisites

Create Pinecone account: Sign up at pinecone.io
Get API key: From the Pinecone console
Create an index: Using the Pinecone console or API

Basic Setup

import { genkit } from 'genkit';
import { pinecone } from 'genkitx-pinecone';
import { googleAI } from '@genkit-ai/google-genai';

const ai = genkit({
  plugins: [
    googleAI(),
    pinecone([
      {
        indexId: 'my-index',
        embedder: googleAI.embedder('gemini-embedding-001'),
      },
    ]),
  ],
});

The API key is automatically read from the PINECONE_API_KEY environment variable.

Configuration

Plugin Configuration

import { pinecone } from 'genkitx-pinecone';
import { googleAI } from '@genkit-ai/google-genai';
import type { PineconeConfiguration } from '@pinecone-database/pinecone';

// Basic configuration
pinecone([
  {
    indexId: 'documents',
    embedder: googleAI.embedder('gemini-embedding-001'),
  },
])

// With explicit API key
const clientParams: PineconeConfiguration = {
  apiKey: process.env.PINECONE_API_KEY,
};

pinecone([
  {
    indexId: 'documents',
    embedder: googleAI.embedder('gemini-embedding-001'),
    clientParams: clientParams,
    embedderOptions: {              // Optional embedder config
      taskType: 'RETRIEVAL_DOCUMENT',
    },
  },
])

// Multiple indexes
pinecone([
  {
    indexId: 'documents',
    embedder: googleAI.embedder('gemini-embedding-001'),
  },
  {
    indexId: 'code-snippets',
    embedder: googleAI.embedder('text-embedding-005'),
  },
])

Custom Content Key

By default, document content is stored in the _content metadata field:

pinecone([
  {
    indexId: 'my-index',
    embedder: googleAI.embedder('gemini-embedding-001'),
    contentKey: 'text',  // Custom key instead of '_content'
  },
])

Usage

Indexing Documents

import { pineconeIndexerRef } from 'genkitx-pinecone';
import { Document } from 'genkit';

// Define indexer
const indexer = pineconeIndexerRef({
  indexId: 'my-index',
});

// Create documents with metadata
const documents = [
  Document.fromText('Genkit is a framework for AI apps.', {
    category: 'framework',
    source: 'docs',
  }),
  Document.fromText('Pinecone is a vector database.', {
    category: 'database',
    source: 'docs',
  }),
];

// Index documents
await ai.index({
  indexer: indexer,
  documents: documents,
});

Using Namespaces

Pinecone supports namespaces for logical data separation:

// Index to a namespace
await ai.index({
  indexer: indexer,
  documents: documents,
  options: {
    namespace: 'production',  // Separate from 'staging', 'test', etc.
  },
});

Retrieving Documents

import { pineconeRetrieverRef } from 'genkitx-pinecone';

// Define retriever
const retriever = pineconeRetrieverRef({
  indexId: 'my-index',
});

// Retrieve relevant documents
const results = await ai.retrieve({
  retriever: retriever,
  query: 'What is Genkit?',
  options: {
    k: 5,  // Return top 5 results (max: 1000)
  },
});

console.log(results.documents);

Retrieve from Namespace

const results = await ai.retrieve({
  retriever: retriever,
  query: 'vector database',
  options: {
    k: 10,
    namespace: 'production',  // Query specific namespace
  },
});

Filtering with Metadata

const results = await ai.retrieve({
  retriever: retriever,
  query: 'database tutorial',
  options: {
    k: 10,
    filter: {
      category: 'database',       // Metadata filter
      source: { $in: ['docs', 'blog'] },
    },
  },
});

RAG Examples

Simple RAG Flow

import { z } from 'genkit';
import { pineconeRetrieverRef } from 'genkitx-pinecone';
import { googleAI } from '@genkit-ai/google-genai';

const retriever = pineconeRetrieverRef({ indexId: 'knowledge-base' });

const ragFlow = ai.defineFlow(
  {
    name: 'ragFlow',
    inputSchema: z.string(),
    outputSchema: z.string(),
  },
  async (query) => {
    // Retrieve context
    const docs = await ai.retrieve({
      retriever: retriever,
      query: query,
      options: { k: 3 },
    });

    // Build context
    const context = docs.documents
      .map(d => d.text)
      .join('\n\n');

    // Generate with context
    const response = await ai.generate({
      model: googleAI.model('gemini-2.5-flash'),
      prompt: `Use this context to answer the question.\n\nContext:\n${context}\n\nQuestion: ${query}`,
    });

    return response.text();
  }
);

Multi-namespace RAG

const multiNamespaceFlow = ai.defineFlow(
  {
    name: 'multiNamespaceRAG',
    inputSchema: z.object({
      query: z.string(),
      sources: z.array(z.string()),  // Namespace names
    }),
  },
  async ({ query, sources }) => {
    // Retrieve from multiple namespaces
    const allDocs = await Promise.all(
      sources.map(namespace =>
        ai.retrieve({
          retriever: retriever,
          query: query,
          options: { k: 3, namespace },
        })
      )
    );

    // Combine results
    const context = allDocs
      .flatMap(result => result.documents)
      .map(d => d.text)
      .join('\n\n');

    // Generate
    const response = await ai.generate({
      model: googleAI.model('gemini-2.5-flash'),
      prompt: `Context:\n${context}\n\nQuestion: ${query}`,
    });

    return response.text();
  }
);

Index Management

Create Index

import { createPineconeIndex } from 'genkitx-pinecone';

await createPineconeIndex({
  options: {
    name: 'my-index',
    dimension: 768,           // Must match embedder dimensions
    metric: 'cosine',         // 'cosine', 'euclidean', or 'dotproduct'
    spec: {
      serverless: {
        cloud: 'aws',
        region: 'us-east-1',
      },
    },
  },
});

Describe Index

import { describePineconeIndex } from 'genkitx-pinecone';

const indexInfo = await describePineconeIndex({
  name: 'my-index',
});

console.log('Index status:', indexInfo.status);
console.log('Dimension:', indexInfo.dimension);
console.log('Vector count:', indexInfo.totalRecordCount);

Delete Index

import { deletePineconeIndex } from 'genkitx-pinecone';

await deletePineconeIndex({
  name: 'old-index',
});

Advanced Features

Sparse Vectors (Hybrid Search)

Combine dense and sparse vectors for hybrid search:

const results = await ai.retrieve({
  retriever: retriever,
  query: 'machine learning',
  options: {
    k: 10,
    sparseVector: {          // BM25 or other sparse embeddings
      indices: [1, 2, 5],
      values: [0.5, 0.8, 0.3],
    },
  },
});

Custom Display Names

import { pineconeRetrieverRef, pineconeIndexerRef } from 'genkitx-pinecone';

const retriever = pineconeRetrieverRef({
  indexId: 'docs-v2',
  displayName: 'Production Documentation',
});

const indexer = pineconeIndexerRef({
  indexId: 'docs-v2',
  displayName: 'Production Documentation',
});

Complete Example

import { genkit, z } from 'genkit';
import {
  pinecone,
  pineconeRetrieverRef,
  pineconeIndexerRef,
  createPineconeIndex,
  describePineconeIndex,
} from 'genkitx-pinecone';
import { googleAI } from '@genkit-ai/google-genai';
import { Document } from 'genkit';

// Initialize
const ai = genkit({
  plugins: [
    googleAI(),
    pinecone([{
      indexId: 'documentation',
      embedder: googleAI.embedder('gemini-embedding-001'),
    }]),
  ],
});

const indexer = pineconeIndexerRef({ indexId: 'documentation' });
const retriever = pineconeRetrieverRef({ indexId: 'documentation' });

// Ensure index exists
try {
  const info = await describePineconeIndex({ name: 'documentation' });
  console.log('Index exists:', info.name);
} catch (error) {
  console.log('Creating index...');
  await createPineconeIndex({
    options: {
      name: 'documentation',
      dimension: 768,
      metric: 'cosine',
      spec: {
        serverless: {
          cloud: 'aws',
          region: 'us-east-1',
        },
      },
    },
  });
}

// Index documents
const docs = [
  Document.fromText('Genkit simplifies AI development.', {
    topic: 'genkit',
    type: 'overview',
  }),
  Document.fromText('Pinecone provides vector search.', {
    topic: 'pinecone',
    type: 'overview',
  }),
];

await ai.index({
  indexer: indexer,
  documents: docs,
  options: { namespace: 'prod' },
});

// RAG flow
const docSearch = ai.defineFlow(
  {
    name: 'documentSearch',
    inputSchema: z.object({
      query: z.string(),
      topic: z.string().optional(),
    }),
  },
  async ({ query, topic }) => {
    const docs = await ai.retrieve({
      retriever: retriever,
      query: query,
      options: {
        k: 5,
        namespace: 'prod',
        filter: topic ? { topic } : undefined,
      },
    });

    const context = docs.documents.map(d => d.text).join('\n');

    const { text } = await ai.generate({
      model: googleAI.model('gemini-2.5-flash'),
      prompt: `Context:\n${context}\n\nQuestion: ${query}`,
    });

    return text;
  }
);

Best Practices

Match Embedder Dimensions

Ensure index dimension matches embedder output:

// Gemini embeddings: 768 dimensions
createPineconeIndex({
  options: {
    name: 'gemini-index',
    dimension: 768,  // Match embedder
  },
})

Use Namespaces for Isolation

// Separate environments
await ai.index({ indexer, documents, options: { namespace: 'production' } });
await ai.index({ indexer, documents, options: { namespace: 'staging' } });
await ai.index({ indexer, documents, options: { namespace: 'testing' } });

// Separate tenants
await ai.index({ indexer, documents, options: { namespace: 'tenant-abc' } });
await ai.index({ indexer, documents, options: { namespace: 'tenant-xyz' } });

Optimize Metadata

Keep metadata small and indexed fields to a minimum:

// Good: Small, relevant metadata
Document.fromText('content', {
  category: 'docs',
  timestamp: Date.now(),
})

// Avoid: Large metadata
Document.fromText('content', {
  fullDocument: largeObject,  // Don't store full docs in metadata
  allTags: longArrayOfTags,   // Keep arrays small
})

Handle Errors

try {
  await ai.retrieve({ retriever, query: 'test' });
} catch (error) {
  if (error.message.includes('Index not found')) {
    console.error('Index does not exist');
  } else if (error.message.includes('PINECONE_API_KEY')) {
    console.error('API key not configured');
  } else {
    console.error('Retrieval error:', error);
  }
}

Configuration Options

Retriever Options

await ai.retrieve({
  retriever: retriever,
  query: 'search query',
  options: {
    k: 10,                            // Max results (1-1000)
    namespace: 'production',          // Query namespace
    filter: {                         // Metadata filter
      category: 'docs',
      year: { $gte: 2023 },
    },
    sparseVector: {                   // Hybrid search
      indices: [1, 2],
      values: [0.5, 0.8],
    },
  },
});

Filter Operators

// Equality
filter: { category: 'docs' }

// Comparison
filter: { 
  year: { $gte: 2020, $lte: 2024 },
  score: { $gt: 0.5 },
}

// Set membership
filter: { 
  category: { $in: ['docs', 'blog'] },
  status: { $nin: ['draft', 'archived'] },
}

// Logical operators
filter: {
  $and: [
    { category: 'docs' },
    { year: { $gte: 2023 } },
  ],
}

Troubleshooting

API Key Issues

Error: Please pass in the API key or set PINECONE_API_KEY Solution: Set environment variable:

export PINECONE_API_KEY=your-api-key

Dimension Mismatch

Error: Dimension mismatch Solution: Ensure index dimension matches embedder output (e.g., 768 for Gemini).

Index Not Ready

Solution: Wait for index to be ready after creation:

let status = 'Initializing';
while (status !== 'Ready') {
  const info = await describePineconeIndex({ name: 'my-index' });
  status = info.status.state;
  await new Promise(resolve => setTimeout(resolve, 1000));
}

Official Plugins

Plugin Development

​Pinecone Plugin

​Installation

​Prerequisites

​Basic Setup

​Configuration

​Plugin Configuration

​Custom Content Key

​Usage

​Indexing Documents

​Using Namespaces

​Retrieving Documents

​Retrieve from Namespace

​Filtering with Metadata

​RAG Examples

​Simple RAG Flow

​Multi-namespace RAG

​Index Management

​Create Index

​Describe Index

​Delete Index

​Advanced Features

​Sparse Vectors (Hybrid Search)

​Custom Display Names

​Complete Example

​Best Practices

​Match Embedder Dimensions

​Use Namespaces for Isolation

​Optimize Metadata

​Handle Errors

​Configuration Options

​Retriever Options

​Filter Operators

​Troubleshooting

​API Key Issues

​Dimension Mismatch

​Index Not Ready

​Links

Build docs developers (and LLMs) love