@pinecone-database/pinecone

Pinecone Node.js Client

This is the Node.js client for Pinecone, written in Typescript. It is a wrapper around the Pinecone OpenAPI spec.

⚠️ 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.

Installation

npm i @pinecone-database/pinecone

Usage

Set the following environment variables:

PINECONE_API_KEY=your_api_key
PINECONE_ENVIRONMENT=your_environment

Initializing the client

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

// Create a client
const client = new PineconeClient();

// Initialize the client
await client.init({
  apiKey: process.env.PINECONE_API_KEY,
  environment: process.env.PINECONE_ENVIRONMENT,
});

Control plane operations

The Pinecone control plane allows you to perform the following operations:

• Create, configure and delete indexes
• Get information about an existing indexes
• Create and delete collections
• Select an index to operate on

Indexes

Create Index

const createRequest: CreateRequest = {
  name: indexName,
  dimension: dimensions,
  metric,
};

await client.createIndex({ createRequest });

Delete Index

await client.deleteIndex({ indexName });

Describe Index

const indexDescription = await client.describeIndex({ indexName });

Example result:

{
  "database": {
    "name": "my-index",
    "metric": "cosine",
    "dimension": 10,
    "replicas": 1,
    "shards": 1,
    "pods": 1,
    "pod_type": "p1.x1"
  },
  "status": {
    "waiting": [],
    "crashed": [],
    "host": "my-index-[project-id].svc.[environment].pinecone.io",
    "port": 433,
    "state": "Ready",
    "ready": true
  }
}

List Indexes

const list = await client.listIndexes();

Example result:

["index1", "index2"]

Select an index

To operate on an index, you must select it. This is done by calling the Index method on the client.

const index = client.Index(indexName);

Collections

Create Collection

const createCollectionRequest: CreateCollectionRequest = {
  name: collection,
  source: indexName,
};
await client.createCollection({ createCollectionRequest });

Delete Collection

await client.deleteCollection(collection);

Describe Collection

const describeCollection = await client.describeCollection({ collectionName });

Example result:

{
  "name": "my-collection",
  "status": "Ready",
  "size": 3059815,
  "dimension": 10
}

List Collections

const list = await client.listCollections();

Example result:

["collection1", "collection2"]

Index operations

The Pinecone index operations allow you to perform the following operations instances of Vector.

A Vector is defined as follows:

type Vector = {
  id: string;
  values: number[];
  metadata?: object;
  sparseValues: {
    indices: [15, 30, 11];
    values: [0.1, 0.2, 0.3];
  }; // optional sparse values
};

After selecting an index to operate on, you can:

Upsert vectors

const upsertRequest: UpsertRequest = {
  vectors,
  namespace,
};
await index.upsert({ upsertRequest });

Query vectors

const vector = [...] // a vector

const queryRequest: QueryRequest = {
  topK: 1,
  vector,
  namespace,
  includeMetadata: true,
  includeValues: true,
}

To query with a sparse vector:

const queryRequest: QueryRequest = {
  topK: 1,
  vector,
  namespace,
  includeMetadata: true,
  includeValues: true,
  sparseVector: {
    indices: [15, 30, 11],
    values: [0.1, 0.2, 0.3],
  },
};

To execute the query:

const queryResponse = await index.query({ queryRequest });

Update a vector

const updateRequest: UpdateRequest = {
  id: vectorId, // the ID of the vector to update
  values: [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0], // the new vector values
  sparseValues: {
    indices: [15, 30, 11],
    values: [0.1, 0.2, 0.3],
  }, // optional sparse values
  setMetadata: metadata, // the new metadata
  namespace,
};
await index.update({ updateRequest });

Fetch vectors by their IDs

const fetchResult = await index.fetch({
  ids: [vectorIDs],
  namespace,
});

Delete vectors

await index.delete1({
  ids: [vectorIDs],
  namespace,
});

Delete all vectors in a namespace

await index.delete1({
  deleteAll: true,
  namespace,
});

Similar packages

Other packages similar to @pinecone-database/pinecone

faiss

Faiss is a library developed by Facebook AI Research for efficient similarity search and clustering of dense vectors. It is highly optimized for performance and can handle large-scale datasets. Unlike Pinecone, Faiss is more of a low-level library and requires more setup and management.

annoy

Annoy (Approximate Nearest Neighbors Oh Yeah) is a C++ library with Python bindings for performing fast approximate nearest neighbor searches. It is particularly useful for read-heavy workloads and is easy to use. However, it lacks some of the advanced features and scalability options provided by Pinecone.

milvus

Milvus is an open-source vector database designed for scalable similarity search and AI applications. It supports various indexing methods and is highly scalable. Milvus offers more flexibility and control over the indexing and querying process compared to Pinecone.