​

Upstash Vector Node.js Client

This is the official Node.js client for Upstash, written in TypeScript.

​

Installation

npm install @upstash/vector
pnpm add @upstash/vector

​

Usage

​

Initializing the client

There are two pieces of configuration required to use the Upstash vector client: an REST token and REST URL. These values can be passed using environment variables or in code through a configuration object. Find your configuration values in the console dashboard at https://console.upstash.com/.

​

Using environment variables

The environment variables used to configure the client are the following:

UPSTASH_VECTOR_REST_URL="your_rest_url"
UPSTASH_VECTOR_REST_TOKEN="your_rest_token"

When these environment variables are set, the client constructor does not require any additional arguments.

import { Index } from "@upstash/vector";

const index = new Index();

​

Using a configuration object

If you prefer to pass configuration in code, the constructor accepts a config object containing the url and token values. This could be useful if your application needs to interact with multiple projects, each with a different configuration.

import { Index } from "@upstash/vector";

const index = new Index({
  url: "<UPSTASH_VECTOR_REST_URL>",
  token: "<UPSTASH_VECTOR_REST_TOKEN>",
});

​

Index operations

Upstash vector indexes support operations for working with vector data using operations such as upsert, query, fetch, delete, stats and reset.

​

Accessing an index

To perform data operations on an index, access it using the index method.

await index.fetch([....], { includeMetadata: true, includeVectors: true });

​

Accessing an index, with metadata typing

If you are storing metadata alongside your vector values, you can pass a type parameter to index() in order to get proper TypeScript typechecking.

type Metadata = {
  title: string,
  genre: 'sci-fi' | 'fantasy' | 'horror' | 'action'
}

await index.upsert([{
  id: '1234',
  vector: [
    .... // embedding values
  ],
  metadata: {
    title: 'Lord of The Rings',
    genre: 'drama',
    category: 'classic'
  }
}])

const results = await index.query<Metadata>({
  vector: [
    ... // query embedding
  ],
  includeVectors: true,
  topK: 1,
})

if (results[0].metadata) {
  // Since we passed the Metadata type parameter above,
  // we can interact with metadata fields without having to
  // do any typecasting.
  const { title, genre, category } = results[0].metadata;
  console.log(`The best match in fantasy was ${title}`)
}

​

Upsert records

Upstash vector expects records inserted into indexes to have the following form:

type UpstashRecord = {
  id: number | string;
  vector: number[];
  metadata?: Record<string, unknown>;
};

// Upsert multiple records
await index.upsert([...]);

// Upsert a single record
await index.upsert({...});

​

Querying

​

Querying with vector values

The query method accepts a large number of options. The dimension of the query vector must match the dimension of your index.

type QueryOptions = {
  vector: number[];
  topK: number;
  includeVectors?: boolean;
  includeMetadata?: boolean;
};

For example, to query by vector values you would pass the vector param in the options configuration. For brevity sake this example query vector is tiny (dimension 2), but in a more realistic use case this query vector would be an embedding outputted by a model. Look at the Example code to see more realistic examples of how to use query.

> await index.query({ topK: 3, vector: [ ... ]})
{
  matches: [
    {
      id: '6345',
      score: 1.00000012,
      vector: [],
      metadata: undefined
    },
    {
      id: '1233',
      score: 1.00000012,
      vector: [],
      metadata: undefined
    },
    {
      id: '4142',
      score: 1.00000012,
      vector: [],
      metadata: undefined
    }
  ],
  namespace: ''
}

You include options to includeMetadata: true or includeVectors: true if you need this information. By default these are not returned to keep the response payload small.

​

Update a record

You may want to update vector vector or metadata. Specify the id and the attribute value you want to update.

await index.upsert({
  id: "18593",
  metadata: { genre: "romance" },
});

​

Fetch records by their IDs

const fetchResult = await index.fetch(["id-1", "id-2"]);

​

Delete records

For convenience there are several delete-related options. You can verify the results of a delete operation by trying to fetch() a record.

// Delete multiple records
await index.delete([...]);

// Delete a single record
await index.delete("id-to-delete");

​

Stats

To get statistics of your index, you can use the client like so:

await index.stats(["id-1", "id-2", "id-3"]);

​

Reset

To delete everything related with that index:

await index.reset();

​

Contributing