Getting Started - Upstash Documentation

@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.
Delete vectors from an index.
Access index stats.
Reset everything related to an index.

You can find the Github Repository here.

Install

npm

npm install @upstash/vector

pnpm

pnpm add @upstash/vector

Usage

Initializing the client

There are two pieces of configuration required to use the Upstash vector client: a 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.