@upstash/vector is a Typescript SDK for Upstash Vector, enabling easier operations on Vector Store with full type coverage.

Using @upstash/vector you can:

  • Upsert a vector with metadata to an index
  • Fetching the vectors with specified IDs
  • Querying a vector over pre-defined embeddings
  • Remove vectors from an index
  • Access index stats
  • Reset everything related to an index

You can find the Github Repository here.

Install

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. You can follow this guide to retrieve credentials.

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>",
});

TypeScript Usage

Index level types

The Vector SDK supports defining your metadata type at the index level for complete type-safety.

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

type Metadata = { genre: string, year: number };

const index = new Index<Metadata>();

Passing a metadata type at the index level will provide strong type safety for the metadata coming back from or required for the following commands:

  • query
  • upsert
  • fetch
  • range

Command level types

In some cases, you might not want to define a metadata type at the index level. In this case, you can either override the index level type definition for a specific command, or pass a metadata type to specific commands instead.

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

type Metadata = { genre: string, year: number };

const index = new Index();

index.upsert<Metadata>({ id: 1, vector: [...], metadata: { 
  genre: "comedy",
  year: 1990
}});

The passing of a strong metadata type is possible for each of the four index operations listed above, we use upsert as an example.