This is the official Node.js SDK for Pinecone, written in TypeScript.
- Reference Documentation
- If you are upgrading from
v0.x, check out the v1 Migration Guide. - If you are upgrading from
v1.x, check out the v2 Migration Guide.
The snippets shown in this README are intended to be concise. For more realistic examples, explore these examples:
There is a breaking change involving the configureIndex operation in this update. The structure of the object passed
when configuring an index has changed to include deletionProtection. The podType and replicas fields can now be updated through the spec.pod object. See Configure pod-based indexes for an example of the code.
- Upgrading to
2.x: There were many changes made in this release to support Pinecone's new Serverless index offering. The changes are covered in detail in the v2 Migration Guide. Serverless indexes are only available in2.xrelease versions or greater. - Upgrading to
1.x: This release officially moved the SDK out of beta, and there are a number of breaking changes that need to be addressed when upgrading from a0.xversion. See the v1 Migration Guide for details.
The Pinecone TypeScript SDK is compatible with TypeScript >=4.1 and Node >=18.x.
npm install @pinecone-database/pinecone
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.
An API key is required to initialize the client. It can be passed using an environment variable or in code through a configuration object. Get an API key in the console.
The environment variable used to configure the API key for the client is the following:
PINECONE_API_KEY="your_api_key"PINECONE_API_KEY is the only required variable. When this environment variable is set, the client constructor does not require any additional arguments.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();If you prefer to pass configuration in code, the constructor accepts a config object containing the apiKey value.
This is the object in which you would pass properties like maxRetries (defaults to 3) for retryable operations
(upsert, update, and configureIndex).
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone({
apiKey: 'your_api_key',
maxRetries: 5,
});If your network setup requires you to interact with Pinecone via a proxy, you can pass a custom ProxyAgent from
the undici library. Below is an example of how to
construct an undici ProxyAgent that routes network traffic through a mitm proxy server while hitting Pinecone's /indexes endpoint.
Note: The following strategy relies on Node's native fetch implementation, released in Node v16 and
stabilized in Node v21. If you are running Node versions
18-21, you may experience issues stemming from the instability of the feature. There are currently no known issues
related to proxying in Node v18+.
import {
Pinecone,
type PineconeConfiguration,
} from '@pinecone-database/pinecone';
import { Dispatcher, ProxyAgent } from 'undici';
import * as fs from 'fs';
const cert = fs.readFileSync('path-to-your-mitm-proxy-cert-pem-file');
const client = new ProxyAgent({
uri: '<your proxy server URI>',
requestTls: {
port: '<your proxy server port>',
ca: cert,
host: '<your proxy server host>',
},
});
const customFetch = (
input: string | URL | Request,
init: RequestInit | undefined
) => {
return fetch(input, {
...init,
dispatcher: client as Dispatcher,
keepalive: true, # optional
});
};
const config: PineconeConfiguration = {
apiKey:
'<your Pinecone API key, available in your dashboard at app.pinecone.io>',
fetchApi: customFetch,
};
const pc = new Pinecone(config);
const indexes = async () => {
return await pc.listIndexes();
};
indexes().then((response) => {
console.log('My indexes: ', response);
});At a minimum, to create a serverless index you must specify a name, dimension, and spec. The dimension
indicates the size of the vectors you intend to store in the index. For example, if your intention was to store and
query embeddings (vectors) generated with OpenAI's textembedding-ada-002 model, you would need to create an index with dimension 1536 to match the output of that model. By default, serverless indexes will have a vectorType of dense.
The spec configures how the index should be deployed. For serverless indexes, you define only the cloud and region where the index should be hosted. For pod-based indexes, you define the environment where the index should be hosted, the pod type and size to use, and other index characteristics. For more information on serverless and regional availability, see Understanding indexes.
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
await pc.createIndex({
name: 'sample-index',
dimension: 1536,
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2',
},
},
tags: { team: 'data-science' },
});You can also use vectorType to create sparse serverless indexes. These indexes enable direct indexing and retrieval of sparse vectors, supporting traditional methods like BM25 and learned sparse models such as pinecone-sparse-english-v0. A sparse index must have a distance metric of dotproduct and does not require a specified dimension. If no
metric is provided with a vectorType of sparse, it will default to dotproduct:
import { Pinecone } from '@pinecone-database/pinecone';
const pc = new Pinecone();
await pc.createIndex({
name: 'sample-index',
metric: 'dotproduct',
spec: {
serverless: {
cloud: 'aws',
region: 'us-west-2',
},
},
tags: { team: 'data-science' },
vectorType: 'sparse',
});