Overview
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
Was this page helpful?