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).
- 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 Embedding: Have Pinecone embed document text with hosted models, so you can search by meaning without managing vectors
- Inference: Hosted embedding and reranking models through
pc.inference - Pinecone Assistant: AI assistants powered by vector database capabilities
- Type Safety: Full TypeScript support with generic type parameters for metadata
- Documentation
- Prerequisites
- Installation
- Productionizing
- Quickstart
- Pinecone Assistant
- More Information
- Issues and Bugs
- Contributing
Note
For notes on breaking changes between versions, see the migration guides.
- 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/nodeThe 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.
npm install @pinecone-database/pineconeThe 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.
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 embedding to have Pinecone generate embeddings from document text.
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.
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);Declare embed on a string field and Pinecone embeds the field's text with a hosted model when you upsert, and embeds your query text when you search. You never handle the vectors yourself.
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 whose body field is embedded by a hosted model
const indexModel = await pc.indexes.create({
name: 'embedded-documents-example',
schema: {
fields: {
body: { type: 'string', embed: { model: 'llama-text-embed-v2' } },
},
},
deployment: { deploymentType: 'managed', cloud: 'aws', region: 'us-west-2' },
waitUntilReady: true,
});
// 3. Upsert plain text; Pinecone generates the embeddings
const index = pc.index({ host: indexModel.host, namespace: 'articles' });
await index.documents.upsert({
documents: [
{
_id: 'rec1',
body: "Apple's first product, the Apple I, was released in 1976.",
category: 'product',
},
{
_id: 'rec2',
body: 'Apples are a great source of dietary fiber, which supports digestion.',
category: 'nutrition',
},
],
});
// 4. Search by meaning with query text
// Newly upserted documents may take time to become searchable.
const results = await index.documents.search({
scoreBy: [{ type: 'embed', field: 'body', query: 'healthy eating' }],
topK: 3,
includeFields: ['body', 'category'],
});
console.log(results.matches);The text is also stored and indexed for full-text search, so the same field supports text scoring. Add sparseEmbed: {} to the field for sparse embeddings. See Integrated embedding for the full set of options.
Indexes created with pc.indexes.createForModel are legacy integrated indexes, read and written through the legacy Records API (upsertRecords and searchRecords). See Legacy Integrated Indexes.
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.
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
- Legacy Integrated Indexes - Indexes created with
createForModel, and the legacy Records API
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
If you notice bugs or have feedback, please file an issue.
You can also get help in the Pinecone Community Forum.
If you'd like to make a contribution, or get setup locally to develop the Pinecone TypeScript SDK, please see our contributing guide