@pinecone-database/pinecone

What is @pinecone-database/pinecone?

@pinecone-database/pinecone is an npm package that provides a client for interacting with the Pinecone vector database. Pinecone is designed for high-performance vector similarity search, making it useful for applications like recommendation systems, semantic search, and machine learning model deployment.

What are @pinecone-database/pinecone's main functionalities?

Initialize Pinecone Client

This code initializes the Pinecone client with the provided API key and environment. Initialization is the first step to interact with the Pinecone database.

const { PineconeClient } = require('@pinecone-database/pinecone');
const client = new PineconeClient();
client.init({ apiKey: 'your-api-key', environment: 'us-west1-gcp' });

Create Index

This code demonstrates how to create a new index in Pinecone. An index is a collection of vectors that you can query against.

const createIndex = async () => {
  await client.createIndex({
    name: 'example-index',
    dimension: 128
  });
};
createIndex();

Insert Vectors

This code inserts vectors into an existing index. Each vector has an ID and a list of values representing its coordinates in the vector space.

const insertVectors = async () => {
  await client.upsert({
    indexName: 'example-index',
    vectors: [
      { id: 'vec1', values: [0.1, 0.2, 0.3] },
      { id: 'vec2', values: [0.4, 0.5, 0.6] }
    ]
  });
};
insertVectors();

Query Vectors

This code queries the index for the top K most similar vectors to the provided query vector. The result contains the IDs and similarity scores of the closest vectors.

const queryVectors = async () => {
  const result = await client.query({
    indexName: 'example-index',
    topK: 2,
    vector: [0.1, 0.2, 0.3]
  });
  console.log(result);
};
queryVectors();

Delete Index

This code deletes an existing index from Pinecone. This is useful for cleanup or when the index is no longer needed.

const deleteIndex = async () => {
  await client.deleteIndex({
    name: 'example-index'
  });
};
deleteIndex();

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.

README

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:

1. Create, configure and delete indexes
2. Get information about an existing indexes
3. Create and delete collections
4. 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,
});