Pinecone TypeScript SDK ·

The official Pinecone TypeScript SDK for building full-text and vector search applications.

Use Pinecone to store, search, and manage documents and high-dimensional vectors. Search document text directly with full-text queries, or use embeddings for semantic search, recommendation systems, and RAG (Retrieval-Augmented Generation).

Features

• Document & Full-Text Search: Store documents, search text across multiple fields, and use query-string scoring with filtering and field selection
• Document Operations: Upsert, fetch, update, and delete documents within namespaces
• Vector Operations: Store, query, and manage high-dimensional vectors with metadata filtering
• Index Management: Create serverless indexes and manage existing pod-based indexes
• Integrated Inference: Built-in embedding and reranking models for end-to-end search workflows
• Pinecone Assistant: AI assistants powered by vector database capabilities
• Type Safety: Full TypeScript support with generic type parameters for metadata

Table of Contents

• Documentation
• Prerequisites
• Installation
• Productionizing
• Quickstart
  • Full-text search with documents
  • Bringing your own vectors
  • Using integrated inference
• Pinecone Assistant
• More Information
• Issues and Bugs
• Contributing

Documentation

• Conceptual docs and guides
• TypeScript Reference Documentation

Upgrading the SDK

[!NOTE] For notes on breaking changes between versions, see the migration guides.

Prerequisites

• The Pinecone TypeScript SDK is compatible with TypeScript >=5.2.0, including the 6.x and 7.x releases, and Node.js >=22.0.0. Node 20 reached end-of-life on 2026-04-30 and no longer receives security patches, so it is no longer supported. CI exercises Node 22.x and 24.x.
• Before you can use the Pinecone SDK, you must sign up for an account and find your API key in the Pinecone console dashboard at https://app.pinecone.io.

Note for TypeScript users: The published type declarations reference the global fetch types (fetch, Request, Response, Blob, ReadableStream). Those come from either @types/node or the dom lib, so a Node project needs @types/node installed:

npm install --save-dev @types/node

The declarations support Node-only TypeScript configurations with lib: ["es2022"], types: ["node"], and skipLibCheck: false; adding "dom" or "webworker" to lib is not required. They reference no Node-only types themselves, so they also compile under TypeScript 6 and 7, where types defaults to [] and @types packages are no longer included automatically. CI compiles a consumer project against TypeScript 5.2 through the current 7.x release, in CommonJS and ESM (module: "nodenext") configurations.

Installation

npm install @pinecone-database/pinecone

Productionizing

The Pinecone TypeScript SDK is intended for server-side use only. Using the SDK within a browser context can expose your API key(s). If you have deployed the SDK to production in a browser, please rotate your API keys.

Quickstart

Choose the workflow that matches your data:

• Documents and full-text search for searchable text and named document fields.
• Bring your own vectors for vector records with embeddings you generate.
• Integrated inference to have Pinecone generate embeddings from text.

Full-text search with documents

Create an index with searchable text fields, upsert documents, and search their contents without generating embeddings. Enable full-text search on each searchable string field with fullTextSearch: {}.

import { Pinecone } from '@pinecone-database/pinecone';

// 1. Instantiate the client using the PINECONE_API_KEY environment variable
const pc = new Pinecone();

// 2. Create an index with full-text search enabled on title and body
const indexModel = await pc.indexes.create({
  name: 'documents-example',
  schema: {
    fields: {
      title: { type: 'string', fullTextSearch: {} },
      body: { type: 'string', fullTextSearch: {} },
    },
  },
  deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-west-2' },
  waitUntilReady: true,
});

// 3. Target a namespace and upsert documents using _id identifiers
const index = pc.index({ host: indexModel.host, namespace: 'articles' });
await index.documents.upsert({
  documents: [
    {
      _id: 'article-1',
      title: 'Growing apples',
      body: 'Apple trees need sunlight and well-drained soil.',
      category: 'gardening',
    },
    {
      _id: 'article-2',
      title: 'Growing pears',
      body: 'Pear trees thrive in sunny orchards.',
      category: 'gardening',
    },
  ],
});

// 4. Search across text fields and select the fields to return
// Newly upserted documents may take time to become searchable.
const results = await index.documents.search({
  scoreBy: [{ type: 'text', fields: ['title', 'body'], query: 'apple' }],
  filter: { category: { $eq: 'gardening' } },
  topK: 5,
  includeFields: ['title', 'body'],
});

console.log(results.matches);

Search matches include _id and _score; use includeFields to return document content. For query-string scoring, replace scoreBy with [{ type: 'query_string', query: 'body:apple' }]. You can also manage documents with index.documents.fetch, index.documents.update, and index.documents.delete.

See Working with Documents for search options and document management examples.

Bringing your own vectors to Pinecone

This example shows how to create an index, add vectors with embeddings you've generated, and query them. This approach gives you full control over your embedding model and vector generation process.

import { Pinecone } from '@pinecone-database/pinecone';

// 1. Instantiate the Pinecone client
// Option A: Pass API key directly
const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

// Option B: Use environment variable (PINECONE_API_KEY)
// const pc = new Pinecone();

// 2. Create a serverless index
const indexModel = await pc.indexes.create({
  name: 'example-index',
  schema: {
    fields: {
      _values: { type: 'dense_vector', dimension: 8, metric: 'cosine' },
    },
  },
  deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-east-1' },
  waitUntilReady: true,
});

// 3. Target the index
const index = pc.index({ host: indexModel.host });

// 4. Upsert vectors with metadata
await index.upsert({
  records: [
    {
      id: 'vec1',
      values: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], // dimension matches the index (8)
      metadata: { genre: 'drama', year: 2020 },
    },
    {
      id: 'vec2',
      values: [0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9],
      metadata: { genre: 'action', year: 2021 },
    },
  ],
});

// 5. Query the index
const queryResponse = await index.query({
  vector: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8], // ... query vector
  topK: 3,
  includeMetadata: true,
});

console.log(queryResponse);

Using integrated inference

This example demonstrates using Pinecone's integrated inference capabilities. You provide raw text data, and Pinecone handles embedding generation and optional reranking automatically. This is ideal when you want to focus on your data and let Pinecone handle the ML complexity.

import { Pinecone } from '@pinecone-database/pinecone';

// 1. Instantiate the Pinecone client
const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

// 2. Create an index configured for use with a particular embedding model
const indexModel = await pc.indexes.createForModel({
  name: 'example-index',
  cloud: 'aws',
  region: 'us-east-1',
  embed: {
    model: 'multilingual-e5-large',
    fieldMap: { text: 'chunk_text' },
  },
  waitUntilReady: true,
});

// 3. Target the index
const index = pc.index({ host: indexModel.host });

// 4. Upsert records with raw text data
// Pinecone will automatically generate embeddings using the configured model
await index.upsertRecords({
  records: [
    {
      id: 'rec1',
      chunk_text:
        "Apple's first product, the Apple I, was released in 1976 and was hand-built by co-founder Steve Wozniak.",
      category: 'product',
    },
    {
      id: 'rec2',
      chunk_text:
        'Apples are a great source of dietary fiber, which supports digestion and helps maintain a healthy gut.',
      category: 'nutrition',
    },
    {
      id: 'rec3',
      chunk_text:
        'Apples originated in Central Asia and have been cultivated for thousands of years, with over 7,500 varieties available today.',
      category: 'cultivation',
    },
    {
      id: 'rec4',
      chunk_text:
        'In 2001, Apple released the iPod, which transformed the music industry by making portable music widely accessible.',
      category: 'product',
    },
  ],
});

// 5. Search for similar records using text queries
// Pinecone handles embedding the query and optionally reranking results
const searchResponse = await index.searchRecords({
  query: {
    inputs: { text: 'Apple corporation' },
    topK: 3,
  },
  rerank: {
    model: 'bge-reranker-v2-m3',
    topN: 2,
    rankFields: ['chunk_text'],
  },
});

console.log(searchResponse);

Pinecone Assistant

The Pinecone Assistant API enables you to create and manage AI assistants powered by Pinecone's vector database capabilities. These Assistants can be customized with specific instructions and metadata, and can interact with files and engage in chat conversations.

import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();

// Create an assistant
const assistant = await pc.assistants.create({
  name: 'product-assistant',
  instructions: 'You are a helpful product recommendation assistant.',
});

// Target the assistant for data operations
const myAssistant = pc.assistant({ name: 'product-assistant' });

// Upload a file
await myAssistant.uploadFile({
  path: 'product-catalog.txt',
  metadata: { source: 'catalog' },
});

// Chat with the assistant
const response = await myAssistant.chat({
  messages: [
    {
      role: 'user',
      content: 'What products do you recommend for outdoor activities?',
    },
  ],
});

console.log(response.message?.content);

For more information on Pinecone Assistant, see the Pinecone Assistant documentation.

More information on usage

Detailed information on specific ways of using the SDK are covered in these guides:

Index Management:

• Serverless Indexes - Create serverless indexes for document, full-text, and vector search
• Pod Indexes - Manage existing pod-based indexes
• Collections - Static copies of pod-based indexes
• Backups - Create and restore from serverless index backups
• Backup Schedules - Create and manage recurring index backups
• Common Operations - List, describe, delete, and configure indexes

Data Operations:

• Working with Documents - Store, search, fetch, update, and delete documents
• Working with Vectors - Upsert, query, fetch, update, and delete vectors
• Namespaces - Organize documents and vectors within an index
• Metadata Filtering - Advanced filtering with operators
• Bulk Import - Import large datasets from object storage

Inference:

• Inference API - Use standalone embedding and reranking models
• Integrated Inference - Index-integrated embedding and reranking

Assistant:

• Getting Started - Quick start guide for Pinecone Assistant
• Chat Operations - Chat, streaming, and context retrieval
• File Management - Upload, upsert, list, describe, and delete files; poll async file operations

TypeScript Features:

• Type Safety - Generic metadata types and type-safe operations
• Async Patterns - Best practices for async/await
• Error Handling - Error types and recovery strategies

Additional Resources:

• FAQ - Frequently asked questions and troubleshooting

Issues and Bugs

If you notice bugs or have feedback, please file an issue.

You can also get help in the Pinecone Community Forum.

Contributing

If you'd like to make a contribution, or get setup locally to develop the Pinecone TypeScript SDK, please see our contributing guide