Node.JS Client
This page provides installation instructions, usage examples, and a reference for the Pinecone Node.JS client.
Warning
This is a public preview ("Beta") client. Test thoroughly before
using this client for production workloads. No SLAs or technical support
commitments are provided for this client. Expect potential breaking
changes in future releases.
Getting Started
Installation
Use the following shell command to install the Node.JS client for use with Node.JS versions 17 and above:
npm install @pinecone-database/pinecone
Alternatively, you can install Pinecone with Yarn:
yarn add @pinecone-database/pinecone
Usage
Initialize the client
To initialize the client, instantiate the PineconeClient
class and call the init
method. The init
method takes an object with the apiKey
and environment
properties:
import { PineconeClient } from "@pinecone-database/pinecone";
const pinecone = new PineconeClient();
await pinecone.init({
environment: "YOUR_ENVIRONMENT",
apiKey: "YOUR_API_KEY",
});
Create index
The following example creates an index without a metadata configuration. By default, Pinecone indexes all metadata.
await pinecone.createIndex({
createRequest: {
name: "example-index",
dimension: 1024,
},
});
The following example creates an index that only indexes the "color" metadata field. Queries against this index cannot filter based on any other metadata field.
await pinecone.createIndex({
createRequest: {
name: "example-index-2",
dimension: 1024,
metadata_config: {
indexed: ["color"],
},
},
});
List indexes
The following example logs all indexes in your project.
const indexesList = await pinecone.listIndexes();
Describe index
The following example logs information about the index example-index
.
const indexDescription = await pinecone.describeIndex({
indexName: "example-index",
});
Delete index
The following example deletes example-index
.
await pinecone.deleteIndex({
indexName: "example-index",
});
Scale replicas
The following example sets the number of replicas and pod type for example-index
.
await pinecone.configureIndex({
indexName: "example-index",
patchRequest: {
replicas: 2,
podType: "p2",
},
});
Describe index statistics
The following example returns statistics about the index example-index
.
const index = pinecone.Index("example-index");
const indexStats = index.describeIndexStats({
describeIndexStatsRequest: {
filter: {},
},
});
Upsert vectors
The following example upserts vectors to example-index
.
const index = pinecone.Index("example-index");
const upsertRequest = {
vectors: [
{
id: "vec1",
values: [0.1, 0.2, 0.3, 0.4],
metadata: {
genre: "drama",
},
},
{
id: "vec2",
values: [0.2, 0.3, 0.4, 0.5],
metadata: {
genre: "action",
},
},
],
namespace: "example-namespace",
};
const upsertResponse = await index.upsert({ upsertRequest });
Query an index
The following example queries the index example-index
with metadata filtering.
const index = pinecone.Index("example-index");
const queryRequest = {
vector: [0.1, 0.2, 0.3, 0.4],
topK: 10,
includeValues: true,
includeMetadata: true,
filter: {
genre: { $in: ["comedy", "documentary", "drama"] },
},
namespace: "example-namespace",
};
const queryResponse = await index.query({ queryRequest });
Delete vectors
The following example deletes vectors by ID.
const index = pinecone.Index("example-index");
await index.delete1({
ids: ["vec1", "vec2"],
namespace: "example-namespace",
});
Fetch vectors
The following example fetches vectors by ID.
const index = pinecone.Index("example-index");
const fetchResponse = await index.fetch({
ids: ["vec1", "vec2"],
namespace: "example-namespace",
});
Update vectors
The following example updates vectors by ID.
const index = pinecone.Index("example-index");
const updateRequest = {
id: "vec1",
values: [0.1, 0.2, 0.3, 0.4],
setMetadata: { genre: "drama" },
namespace: "example-namespace",
};
const updateResponse = await index.update({ updateRequest });
Create collection
The following example creates the collection example-collection
from example-index
.
const createCollectionRequest = {
name: "example-collection",
source: "example-index",
};
await pinecone.createCollection({
createCollectionRequest,
});
List collections
The following example returns a list of the collections in the current project.
const collectionsList = await pinecone.listCollections();
Describe a collection
The following example returns a description of the collection example-collection
.
const collectionDescription = await pinecone.describeCollection({
collectionName: "example-collection",
});
Delete a collection
The following example deletes the collection example-collection
.
await pinecone.deleteCollection({
collectionName: "example-collection",
});
Reference
For the REST API or other clients, see the API reference.
init()
pinecone.init(configuration: PineconeClientConfiguration)
Initialize the Pinecone client.
Parameters | Type | Description |
---|---|---|
configuration | PineconeClientConfiguration | The configuration for the Pinecone client. |
Types
PineconeClientConfiguration
Parameters | Type | Description |
---|---|---|
apiKey | string | The API key for the Pinecone service. |
environment | string | The cloud environment of your Pinecone project. |
Example:
import { PineconeClient } from "@pinecone-database/pinecone";
const pinecone = new PineconeClient();
await pinecone.init({
apiKey: "YOUR_API_KEY",
environment: "YOUR_ENVIRONMENT",
});
configureIndex()
pinecone.configure_index(indexName: string, patchRequest?: PatchRequest)
Configure an index to change pod type and number of replicas.
Parameters | Type | Description |
---|---|---|
requestParameters | ConfigureIndexRequest | Index configuration parameters. |
Types
ConfigureIndexRequest
Parameters | Type | Description |
---|---|---|
indexName | string | The name of the index. |
patchRequest | PatchRequest | (Optional) Patch request parameters. |
PatchRequest
Parameters | Type | Description |
---|---|---|
replicas | number | (Optional) The number of replicas to configure for this index. |
podType | string | (Optional) The new pod type for the index. One of s1 , p1 , or p2 appended with . and one of x1 , x2 , x4 , or x8 . |
Example:
const newNumberOfReplicas = 4;
const newPodType = "s1.x4";
await pinecone.configureIndex({
indexName: "example-index",
patchRequest: {
replicas: newNumberOfReplicas,
podType: newPodType,
},
});
createCollection()
pinecone.createCollection(requestParameters: CreateCollectionOperationRequest)
Create a collection from an index.
Parameters | Type | Description |
---|---|---|
requestParameters | CreateCollectionOperationRequest | Create collection operation wrapper |
Types
CreateCollectionOperationRequest
Parameters | Type | Description |
---|---|---|
createCollectionRequest | CreateCollectionRequest | Collection request parameters. |
CreateCollectionRequest
Parameters | Type | Description |
---|---|---|
name | string | The name of the collection to be created. |
source | string | The name of the source index to be used as the source for the collection. |
Example:
await pinecone.createCollection({
createCollectionRequest: {
name: "example-collection",
source: "example-index",
},
});
createIndex()
pinecone.createIndex(requestParameters?: CreateIndexRequest)
Create an index.
Parameters | Type | Description |
---|---|---|
requestParameters | CreateIndexRequest | Create index operation wrapper |
Types
CreateIndexRequest
Parameters | Type | Description |
---|---|---|
createRequest | CreateRequest | Create index request parameters |
CreateRequest
Parameters | Type | Description |
---|---|---|
name | str | The name of the index to be created. The maximum length is 45 characters. |
dimension | integer | The dimensions of the vectors to be inserted in the index. |
metric | str | (Optional) The distance metric to be used for similarity search: 'euclidean', 'cosine', or 'dotproduct'. |
pods | int | (Optional) The number of pods for the index to use, including replicas. |
replicas | int | (Optional) The number of replicas. |
pod_type | str | (Optional) The new pod type for the index. One of s1 , p1 , or p2 appended with . and one of x1 , x2 , x4 , or x8 . |
metadata_config | object | (Optional) Configuration for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when metadata_config is present, only specified metadata fields are indexed. To specify metadata fields to index, provide a JSON object of the following form: {"indexed": ["example_metadata_field"]} |
source_collection | str | (Optional) The name of the collection to create an index from. |
Example:
// The following example creates an index without a metadata
// configuration. By default, Pinecone indexes all metadata.
await pinecone.createIndex({
createRequest: {
name: "pinecone-index",
dimension: 1024,
},
});
// The following example creates an index that only indexes
// the 'color' metadata field. Queries against this index
// cannot filter based on any other metadata field.
await pinecone.createIndex({
createRequest: {
name: "example-index-2",
dimension: 1024,
metadata_config: {
indexed: ["color"],
},
},
});
deleteCollection()
pinecone.deleteCollection(requestParameters: DeleteCollectionRequest)
Delete an existing collection.
Types
Parameters | Type | Description |
---|---|---|
requestParameters | DeleteCollectionRequest | Delete collection request parameters |
DeleteCollectionRequest
Parameters | Type | Description |
---|---|---|
collectionName | string | The name of the collection to delete. |
Example:
await pinecone.deleteCollection({
collectionName: "example-collection",
});
deleteIndex()
pinecone.deleteIndex(requestParameters: DeleteIndexRequest)
Delete an index.
Types
Parameters | Type | Description |
---|---|---|
requestParameters | DeleteIndexRequest | Delete index request parameters |
DeleteIndexRequest
Parameters | Type | Description |
---|---|---|
indexName | string | The name of the index to delete. |
Example:
await pinecone.deleteIndex({
indexName: "example-index",
});
describeCollection()
pinecone.describeCollection(requestParameters: DescribeCollectionRequest)
Get a description of a collection.
Types
Parameters | Type | Description |
---|---|---|
requestParameters | DescribeCollectionRequest | Describe collection request parameters |
DescribeCollectionRequest
Parameters | Type | Description |
---|---|---|
collectionName | string | The name of the collection. |
Example:
const collectionDescription = await pinecone.describeCollection({
collectionName: "example-collection",
});
Return:
collectionMeta
:object
Configuration information and deployment status of the collection.name
:string
The name of the collection.size
:integer
The size of the collection in bytes.status
:string
The status of the collection.
describeIndex()
pinecone.describeIndex(requestParameters: DescribeIndexRequest)
Get a description of an index.
Types
Parameters | Type | Description |
---|---|---|
requestParameters | DescribeIndexRequest | Describe index request parameters |
DescribeIndexRequest
Parameters | Type | Description |
---|---|---|
indexName | string | The name of the index. |
Types
Returns:
database
:object
name
:string
The name of the index.dimension
:integer
The dimensions of the vectors to be inserted in the index.metric
:string
The distance metric used for similarity search: 'euclidean', 'cosine', or 'dotproduct'.pods
:integer
The number of pods the index uses, including replicas.replicas
:integer
The number of replicas.pod_type
:string
The pod type for the index. One ofs1
,p1
, orp2
appended with.
and one ofx1
,x2
,x4
, orx8
.metadata_config
:object
Configuration for the behavior of Pinecone's internal metadata index. By default, all metadata is indexed; when metadata_config is present, only specified metadata fields are indexed. To specify metadata fields to index, provide a JSON object of the following form:{"indexed": ["example_metadata_field"]}
status
:object
ready
:boolean
Whether the index is ready to serve queries.state
:string
One ofInitializing
,ScalingUp
,ScalingDown
,Terminating
, orReady
.
Example:
const indexDescription = await pinecone.describeIndex({
indexName: "example-index",
});
listCollections
pinecone.listCollections()
Return a list of the collections in your project.
Example:
const collections = await pinecone.listCollections();
Returns:
array
ofstrings
The names of the collections in your project.
listIndexes
pinecone.listIndexes()
Return a list of your Pinecone indexes.
Returns:
array
ofstrings
The names of the indexes in your project.
Example:
const indexesList = await pinecone.listIndexes();
Index()
pinecone.Index(indexName: string)
Construct an Index object.
Parameters | Type | Description |
---|---|---|
indexName | string | The name of the index. |
Example:
const index = pinecone.Index("example-index");
Index.delete1()
index.delete(requestParameters: Delete1Request)
Delete items by their ID from a single namespace.
Parameters | Type | Description |
---|---|---|
requestParameters | Delete1Request | Delete request parameters |
Types
Delete1Request
Parameters | Type | Description |
---|---|---|
ids | Array | (Optional) The IDs of the items to delete. |
delete_all | boolean | (Optional) Indicates that all vectors in the index namespace should be deleted. |
namespace | str | (Optional) The namespace to delete vectors from, if applicable. |
Types
Example:
await index.delete1({
ids: ["example-id-1", "example-id-2"],
namespace: "example-namespace",
});
Index.describeIndexStats()
index.describeIndexStats(requestParameters: DescribeIndexStatsOperationRequest)
Returns statistics about the index's contents, including the vector count per namespace and the number of dimensions.
Parameters | Type | Description |
---|---|---|
requestParameters | DescribeIndexStatsOperationRequest | Describe index stats request wrapper |
Types
DescribeIndexStatsOperationRequest
Parameters | Type | Description |
---|---|---|
describeIndexStatsRequest | DescribeIndexStatsRequest | Describe index stats request parameters |
DescribeIndexStatsRequest
parameter | Type | Description |
---|---|---|
filter | object | (Optional) A metadata filter expression. |
Returns:
namespaces
:object
A mapping for each namespace in the index from the namespace name to a
summary of its contents. If a metadata filter expression is present, the summary will reflect only vectors matching that expression.dimension
:int64
The dimension of the indexed vectors.indexFullness
:float
The fullness of the index, regardless of whether a metadata filter expression was passed. The granularity of this metric is 10%.totalVectorCount
:int64
The total number of vectors in the index.
Example:
const indexStats = await index.describeIndexStats({
describeIndexStatsRequest: {},
});
Read more about filtering for more detail.
Index.fetch()
index.fetch(requestParameters: FetchRequest)
The Fetch operation looks up and returns vectors, by ID, from a single namespace. The returned vectors include the vector data and metadata.
Parameters | Type | Description |
---|---|---|
requestParameters | FetchRequest | Fetch request parameters |
Types
FetchRequest
Parameters | Type | Description |
---|---|---|
ids | Array | The vector IDs to fetch. Does not accept values containing spaces. |
namespace | string | (Optional) The namespace containing the vectors. |
Returns:
vectors
:object
Contains the vectors.namespace
:string
The namespace of the vectors.
Example:
const fetchResponse = await index.fetch({
ids: ["example-id-1", "example-id-2"],
namespace: "example-namespace",
});
Index.query()
index.query(requestParameters: QueryOperationRequest)
Search a namespace using a query vector. Retrieves the ids of the most similar items in a namespace, along with their similarity scores.
Parameters | Type | Description |
---|---|---|
requestParameters | QueryOperationRequest | The query operation request wrapper. |
Types
Parameters | Type | Description |
---|---|---|
queryRequest | QueryRequest | The query operation request. |
QueryRequest
Parameter | Type | Description |
---|---|---|
namespace | string | (Optional) The namespace to query. |
topK | number | The number of results to return for each query. |
filter | object | (Optional) The filter to apply. You can use vector metadata to limit your search. See https://www.pinecone.io/docs/metadata-filtering/. |
includeValues | boolean | (Optional) Indicates whether vector values are included in the response. Defaults to false . |
includeMetadata | boolean | (Optional) Indicates whether metadata is included in the response as well as the ids. Defaults to false . |
vector | Array | (Optional) The query vector. This should be the same length as the dimension of the index being queried. Each query() request can contain only one of the parameters id or vector . |
id | string | (Optional) The unique ID of the vector to be used as a query vector. Each query() request can contain only one of the parameters vector or id . |
Example:
const queryResponse = await index.query({
queryRequest: {
namespace: "example-namespace",
topK: 10,
filter: {
genre: { $in: ["comedy", "documentary", "drama"] },
},
includeValues: true,
includeMetadata: true,
vector: [0.1, 0.2, 0.3, 0.4],
},
});
Index.update()
index.update(requestParameters: UpdateOperationRequest)
Updates vectors in a namespace. If a value is included, it will overwrite the previous value.
If setMetadata
is included in the updateRequest
, the values of the fields specified in it will be added or overwrite the previous value.
Parameters | Type | Description |
---|---|---|
requestParameters | UpdateOperationRequest | The update operation wrapper |
Types
UpdateOperationRequest
Parameters | Type | Description |
---|---|---|
updateRequest | UpdateRequest | The update request. |
UpdateRequest
Parameter | Type | Description |
---|---|---|
id | string | The vector's unique ID. |
values | Array | (Optional) Vector data. |
setMetadata | object | (Optional) Metadata to set for the vector. |
namespace | string | (Optional) The namespace containing the vector. |
Example:
const updateResponse = await index.update({
updatedRequest: {
id: "vec1",
values: [0.1, 0.2, 0.3, 0.4],
setMetadata: {
genre: "drama",
},
namespace: "example-namespace",
},
});
Index.upsert()
index.upsert(requestParameters: UpsertOperationRequest)
Writes vectors into a namespace. If a new value is upserted for an existing vector ID, it will overwrite the previous value.
Parameters | Type | Description |
---|---|---|
requestParameters | UpsertOperationRequest | Upsert operation wrapper |
Types
UpsertOperationRequest
Parameters | Type | Description |
---|---|---|
upsertRequest | UpsertRequest | The upsert request. |
UpsertRequest
| Parameter | Type | Description |
| vectors
| Array | An array containing the vectors to upsert. Recommended batch limit is 100 vectors.id
(str) - The vector's unique id.values
([float]) - The vector data.metadata
(object) - (Optional) Metadata for the vector. |
| namespace
| string | (Optional) The namespace name to upsert vectors. |
Vector
Parameter | Type | Description |
---|---|---|
id | string | The vector's unique ID. |
values | Array | Vector data. |
metadata | object | (Optional) Metadata for the vector. |
Returns:
upsertedCount
:int64
The number of vectors upserted.
Example:
const upsertResponse = await index.upsert({
upsertRequest: {
vectors: [
{
id: "vec1",
values: [0.1, 0.2, 0.3, 0.4],
metadata: {
genre: "drama",
},
},
{
id: "vec2",
values: [0.1, 0.2, 0.3, 0.4],
metadata: {
genre: "comedy",
},
},
],
namespace: "example-namespace",
},
});
Updated 5 days ago