freshcrate
Skin:/
Home > Databases > pinecone-ts-client

pinecone-ts-client

The official TypeScript/Node client for the Pinecone vector database

Why this rank:Strong adoptionRelease freshnessHealthy release cadence

Description

The official TypeScript/Node client for the Pinecone vector database

README

Pinecone TypeScript SDK ยท License npm npmGitHub Workflow Status (with event)

The official Pinecone TypeScript SDK for building vector search applications with AI/ML.

Pinecone is a vector database that makes it easy to add vector search to production applications. Use Pinecone to store, search, and manage high-dimensional vectors for applications like semantic search, recommendation systems, and RAG (Retrieval-Augmented Generation).

Features

  • Vector Operations: Store, query, and manage high-dimensional vectors with metadata filtering
  • Serverless & Pod Indexes: Choose between serverless (auto-scaling) or pod-based (dedicated) 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

Upgrading the SDK

Note

For notes on changes between major versions, see the migration guides:

Prerequisites

  • The Pinecone TypeScript SDK is compatible with TypeScript >=5.2.0 and Node.js >=20.0.0.
  • 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: This SDK uses Node.js built-in modules in its type definitions. If you're using TypeScript, ensure you have @types/node installed in your project:

npm install --save-dev @types/node

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

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.createIndex({
  name: 'example-index',
  dimension: 1536,
  metric: 'cosine',
  spec: {
    serverless: {
      cloud: 'aws',
      region: 'us-east-1',
    },
  },
});

// 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 should match index (1536)
      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.createIndexForModel({
  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.createAssistant({
  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:

Data Operations:

Inference:

Assistant:

TypeScript Features:

Additional Resources:

  • FAQ - Frequently asked questions and troubleshooting

Issues & 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

Release History

VersionChangesUrgencyDate
v7.2.0### Streaming file uploads for Assistant `uploadFile` now accepts a `Buffer`, `Blob`, or Node.js `ReadableStream` directly, in addition to the existing local file path. This makes it possible to forward an incoming HTTP upload to the Assistant without writing the file to disk or buffering it in memory first. ```typescript // Existing path-based usage โ€” unchanged await assistant.uploadFile({ path: 'report.pdf' }); // New: upload from a Buffer (e.g. multer memory storage) await assistaHigh4/10/2026
v7.1.0This release adds support for creating and configuring index `readCapacity` for BYOC indexes. ```typescript // Create a BYOC index with dedicated read capacity await pinecone.createIndex({ name: 'my-byoc-index', dimension: 1536, metric: 'cosine', spec: { byoc: { environment: 'aws-us-east-1-b921', readCapacity: { mode: 'Dedicated', nodeType: 'b1', manual: { replicas: 1, shards: 1 }, }, }, }, }); ``` It also includeLow2/19/2026
v7.0.0# Release v7.0.0 This version of the Pinecone Node SDK depends on version `2025-10` of the Pinecone API. You can read more about versioning [here](https://docs.pinecone.io/reference/api/introduction#versioning). This v7 SDK release line should continue to receive fixes as long as the `2025-10` API version is in support. ## Breaking Changes ### Index Targeting The preferred way to target an index has changed. You must now pass an options object to `pc.index()` instead of string argumeLow2/1/2026
v6.1.4## What's changed This patch release adds an optional configuration that can allow AI coding agents working with the SDK to identify themselves. This information is incorporated into request User-Agent headers to help us track how our product is being used. ```typescript const pc = new Pinecone({ apiKey: 'your-api-key', caller: { provider: 'google', model: 'gemini' } }); ``` **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v6.1.3..Low1/22/2026
v6.1.3This release fixes a bug in `Assistant.listFiles()` when using a `filter` - there's no need to provide a top-level `metadata` key inside of the filter object. ## What's Changed * Handle errors in `cleanupResources` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/351 * Add `tsx` as a `devDependency`, clean up `setup` GH action by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/352 * Fix list files with filter in Assistant by @avi1mizrahLow11/3/2025
v6.1.2`Assistant.describeFile` now exposes `includeUrl` as an optional argument, and it will default to `true` if not provided. `sourceCollection` is also now exposed on `CreateIndexServerlessSpec` and `IndexModel`. ## What's Changed * Expose `includeUrl` in `Assistant.describeFile`, add `sourceCollection` for serverless by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/349 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v6.1.1...v6.1.2Low7/22/2025
v6.1.1## What's Changed * Regenerate core, expose `privateHost` on `IndexModel`, and `temperature` on `ChatOptions` and `ChatCompletionOptions` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/348 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v6.1.0...v6.1.1Low6/14/2025
v6.1.0This release adds a new `ChatContextOptions` type which allows passing `contextOptions` in `ChatOptions` when calling `chat` or `chatStream`. `ChatContextOptions` supports passing `topK` and `snippetSize`. There have also been fixes made to `context` and `chat` methods to fix issues with argument parameters not being properly passed with the requests. ## What's Changed * Add `ChatContextOptions` to `ChatOptions` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/347Low6/1/2025
v6.0.1This patch fixes an issue with the `listBackups` method not applying pagination to project-level operations. There have also been additional types exported from the top of the package for working with backups and inference models. ## What's Changed * Regenerate `2025-04`, add pagination to list project backups by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/346 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v6.0.0...v6.0.1Low5/20/2025
v6.0.0This version of the Pinecone Node SDK depends on version `2025-04` of the Pinecone API. You can read more about versioning [here](https://docs.pinecone.io/reference/api/versioning). This v6 SDK release line should continue to receive fixes as long as the `2025-04` API version is in support. ## Features ### Namespaces You now have the ability to work more explicitly with namespaces that are associated with an index. There have been several namespace methods added to the `Index` class: Low5/10/2025
v5.1.2This patch corrects an issue with runtime validation and TypeScript types not allowing the `embed` parameter in `ConfigureIndexRequest`. Several dev dependencies for jest have also been updated, along with some tweaks to the integration test suite to prevent hangs in CI. ## What's Changed * Allow `embed` as a parameter to `configureIndex` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/338 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-clientLow4/23/2025
v5.1.1Fixes an issue where the typing for the `upsertRecords` method did not accept `_id` as an object argument. The `_id` and `_score` values are now properly returned from the `searchRecords` method instead of mapped values. ## What's Changed * Fix `_id` and `_score` in records APIs by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/334 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v5.1.0...v5.1.1Low3/4/2025
v5.1.0## Features ### Indexes with Integrated Inference This release adds a new `createIndexForModel` method as well as `upsertRecords`, and `searchRecords` methods. Together these methods provide a way for you to easily store your data and let us manage the process of creating embeddings. To learn about available models, see the [Model Gallery](https://docs.pinecone.io/models/overview). ```typescript import { Pinecone } from '@pinecone-database/pinecone'; // 1. Instantiate the Pinecone cLow2/28/2025
v5.0.2Types `Embedding` and `EmbeddingsListUsage` are now exported from the top of the client package. **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v5.0.1...v5.0.2Low2/20/2025
v5.0.1## What's Changed * Remove `EmbeddingsList` custom class by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/330 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v5.0.0...v5.0.1Low2/20/2025
v5.0.0This version of the Pinecone Node SDK depends on version `2025-01` of the Pinecone API. You can read more about versioning [here](https://docs.pinecone.io/reference/api/versioning). This v5 SDK release line should continue to receive fixes as long as the `2025-01` API version is in support. ## Features ### Sparse index support You can now work with sparse-only indexes. These indexes enable direct indexing and retrieval of sparse vectors, supporting traditional methods like BM25 and learneLow2/15/2025
4.1.0--- ## Features ### Index tags Users can now [tag indexes](https://docs.pinecone.io/guides/indexes/manage-indexes#configure-index-tags) with key:value pairs for categorizing and identifying indexes. You can add tags when [creating an index](https://docs.pinecone.io/guides/indexes/create-an-index), or modify/delete tags when [configuring an index](https://docs.pinecone.io/guides/indexes/manage-indexes). Example code: ```typescript import { Pinecone } from '@pinecone-database/pinecone'; cLow1/9/2025
v4.0.0--- ## Features This version of the Typescript client introduces two new endpoints: [Rerank](https://docs.pinecone.io/guides/inference/rerank) and [Import](https://docs.pinecone.io/guides/data/import-data). ### Rerank `Rerank` provides users the ability to rerank documents in descending relevance-order against a given query. Reranking documents is a common ["second-pass" ranking strategy](https://www.pinecone.io/learn/refine-with-rerank/) broadly used in retrieval applications. ExampleLow10/23/2024
v3.0.3## Fixes * Remove extra logging from getFetch() s/o @maxmetcalfe in https://github.com/pinecone-io/pinecone-ts-client/pull/280 * Some general fixes/internal enhancements to CI workflows ## New Contributors * @maxmetcalfe made their first contribution in https://github.com/pinecone-io/pinecone-ts-client/pull/280 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/3.0.2...v3.0.3 Low9/11/2024
3.0.2## Fixes ### Remove `util:node` function This patch removes a native Node utility function that was causing issues for users running in `Edge`. There are no downstream affects of its removal; code should run as it previously was without interruptions or changes. ## New Contributors * @anawishnoff made their first contribution in https://github.com/pinecone-io/pinecone-ts-client/pull/245 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v3.0.1...3.0.2Low8/26/2024
v3.0.1## Fixes ### Compatibility with Edge runtimes This patch removes the `@sinclair/typebox` and `ajv` libraries, which caused compatibility issues for users running in Edge runtimes (Cloudflare, Vercel, etc.). ### Removal of `crossFetch` ponyfill Since this Typescript client no longer supports versions of Node <18, we can remove the `crossFetch` ponyfill from `src/utils/fetch.ts`, as it was only necessary as a failsafe for users running older versions of Node. ## New Contributors * @jLow8/20/2024
v3.0.0## Features ### API versioning This updated release of the Pinecone TypeScript SDK depends on API version `2024-07`. This v3 SDK release line should continue to receive fixes as long as the `2024-07` API version is in support. ### Inference API Try out Pinecone's new [Inference API](https://docs.pinecone.io/guides/inference/understanding-inference), currently in public preview. ```typescript import { Pinecone } from '@pinecone-database/pinecone'; const client = new Pinecone({Low7/19/2024
v2.2.2This patch fixes a bug when instantiating multiple instances of `Pinecone` and using multiple API keys targeting different indexes. The singleton cache that resolves index addresses will no longer hang on to the first API key it used to describe an index. ## What's Changed * Update README.md by @lnhsingh in https://github.com/pinecone-io/pinecone-ts-client/pull/216 * Fix `IndexHostSingleton` holding onto one instance of `ManageIndexesAPI` by @austin-denoble in https://github.com/pinecone-ioLow6/1/2024
v2.2.1This patch fixes an issue with using `sourceTag` as an argument without disabling runtime validations. ## What's Changed * Remove `merge` workflow by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/213 * Remove serverless public preview warnings by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/214 * Include `sourceTag` in `PineconeConfigurationSchema` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/215 **Low5/10/2024
v2.2.0### `sourceTag` added to `PineconeConfiguration` The SDK now supports optionally passing a `sourceTag` when instantiating the Pinecone client. This tag allows requests made by the SDK to be attributed via the user-agent. ```javascript import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: 'my-api-key', sourceTag: 'my-source-tag' }); // Requests made from the client will now have this tag applied to the user-agent ``` ## What's Changed * Add `sourcLow3/27/2024
v2.1.1Exports the `ListResponse` interface so it can be used by consumers of the client. ## What's Changed * Export `ListResponse` type from generated core, add docstring for `ListOptions` by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/210 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v2.1.0...v2.1.1Low3/26/2024
v2.1.0## Listing record ids by prefix in a namespace (for serverless indexes) We've [implemented](https://github.com/pinecone-io/pinecone-ts-client/pull/202) SDK support for a new data plane endpoint used to list ids by prefix in a given namespace. If no prefix or an empty string is passed, this can be used to list all ids in a namespace. The index class now has a `listPaginated` function. With clever assignment of record ids, this can be used to help model hierarchical relationships between difLow3/6/2024
v2.0.1Fixes a build issue that was caused during our automated release process. ## What's Changed * Remove spruce workflows and references to release in version.json by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/195 **Full Changelog**: https://github.com/pinecone-io/pinecone-ts-client/compare/v2.0.0...v2.0.1Low1/17/2024
v2.0.0This release sees the introduction of the ability to create and manage serverless indexes. There are fundamental changes to control plane operations which include adjustments to function arguments and responses. See below for a summary of changes, and for a more detailed guide take a look at the [v2-migration.md](https://github.com/pinecone-io/pinecone-ts-client/blob/main/v2-migration.md), the [README.md](https://github.com/pinecone-io/pinecone-ts-client/blob/main/README.md), or the [client refeLow1/16/2024
v1.1.3In this release we've updated the client reference documentation link in the `README.md`, and moved a number of non-runtime dependencies into `devDependencies`. ## What's Changed * Update README Reference Documentation link by @austin-denoble in https://github.com/pinecone-io/pinecone-ts-client/pull/150 * Move non-runtime related deps to devDependencies by @SalmonMode in https://github.com/pinecone-io/pinecone-ts-client/pull/175 ## New Contributors * @SalmonMode made their first contribLow1/13/2024
v1.1.2In this release we've included a fix for handling the global `process` object on certain edge platforms such as Cloudflare Workers. This should prevent runtime errors in environments where `process` is not available. ## What's Changed ### Fixes & troubleshooting * Check for `process` existence before accessing it by @omarestrella in https://github.com/pinecone-io/pinecone-ts-client/pull/147 ### Docs * Fix <a /> styling in dark mode by @austin-denoble in https://github.com/pinecone-io/piLow10/24/2023
v1.1.1We are still working with some users to troubleshoot [unexplained problems with the `query` method](https://github.com/pinecone-io/pinecone-ts-client/issues/124). These errors seem to be somehow related to a specific environment, dependency, or usage pattern because the have not been able to reproduce the `query` error in our integration testing and sample projects, including a [nextjs project running on Vercel](https://github.com/pinecone-io/pinecone-vercel-starter). In this release, we haveLow10/10/2023
v1.1.0## Fixed: Next.js fetch compatibility In this release we made some adjustments to how we polyfill `fetch` (which is not natively supported in all versions of node) to avoid conflicting with the Next.js framework. Next.js expects you to use `@vercel/fetch` and stubs out other polyfills to keep the bundle small, so the [cross-fetch](https://www.npmjs.com/package/cross-fetch) polyfill we depend on was not working as expected. We have tested these changes in an updated version of our [pineconLow9/28/2023
v1.0.1This fast-follow to last week's v1 release addresses a number of issues that have been reported by our users. Thank you to everyone who provided feedback. ## Bugs addressed in this release - #102 Typescript version-specific compilation problems - #105 Configuration-specific conflicts with web types in `lib.dom.d.ts` - #118 Some methods failing due to improper usage of the `cross-fetch` polyfill - #108 Use of node libraries breaking [Edge Runtime](https://edge-runtime.vercel.app/) InLow9/14/2023
v1.0.0This release adds a new module export, `Pinecone`, that is an all-new client for calling Pinecone from your TypeScript applications. See the [README](./README.md) docs and [Migration guide](./v1-migration.md) to get started. ## Features in this release - **Simplified library initialization**. Now you can simply `new Pinecone()` to make a client instance without the need for any awkward async initialization steps. The new client can also read the `PINECONE_ENVIRONMENT` and `PINECONE_API_KELow9/7/2023
v0.1.5### Fixes - Remove `process.nextTick()` to fix error in edge runtime #44 Low5/10/2023

Dependencies & License Audit

Loading dependencies...

Similar Packages

lancedbDeveloper-friendly OSS embedded retrieval library for multimodal AI. Search More; Manage Less.python-v0.33.1-beta.2
examplesJupyter Notebooks to help you get hands-on with Pinecone vector databasesmain@2026-06-03
genkitOpen-source framework for building AI-powered apps in JavaScript, Go, and Python, built and used in production by Googlev1.36.0
typescript-clientOfficial Weaviate TypeScript Clientv3.13.0
ai-real-estate-assistantAdvanced AI Real Estate Assistant using RAG, LLMs, and Python. Features market analysis, property valuation, and intelligent search.v5.0.7

More from pinecone-io

examplesJupyter Notebooks to help you get hands-on with Pinecone vector databases
pinecone-python-clientThe Pinecone Python client

More in Databases

milvusMilvus is a high-performance, cloud-native vector database built for scalable vector ANN search
WeKnoraLLM-powered framework for deep document understanding, semantic retrieval, and context-aware answers using RAG paradigm.
ai-real-estate-assistantAdvanced AI Real Estate Assistant using RAG, LLMs, and Python. Features market analysis, property valuation, and intelligent search.
alibabacloud-adb20211201Alibaba Cloud adb (20211201) SDK Library for Python