Skip to main content
@upstash/search is a TypeScript SDK for Upstash AI Search. Using @upstash/search you can:
  • Perform AI-powered search queries
  • Upsert documents to an index
  • Fetch documents by their IDs
  • Delete documents from a database
  • Access database stats
  • Reset databases
You can find the GitHub Repository here.

​
Installation

npm install @upstash/search

​
Usage

​
Initializing the client

There are two pieces of configuration required to use the Upstash search client:
  • a REST token
  • a REST URL
These values can be passed using environment variables or through a configuration object. Find these connection details in the console dashboard.
You can follow this guide to retrieve the following credentials. 
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
When these environment variables are set, the client constructor does not require any additional arguments. 
import { Search } from "@upstash/search";

const client = Search.fromEnv();
const index = client.index("movies")

​
Using a configuration object

The Search class accepts a config object containing the url and token values. This could be useful if your application needs to interact with multiple databases, each with a different configuration. 
import { Search } from "@upstash/search";

const client = new Search({
  url: "<SEARCH_INDEX_REST_URL>",
  token: "<SEARCH_INDEX_REST_TOKEN>",
});

const index = client.index("movies")

​
Typescript

The Search SDK supports defining your content and metadata types at the index level for complete type-safety. 
import { Search } from "@upstash/search";
const client = new Search();

type Content = { title: string, genre: string };
type Metadata = { year: number };
const index = client.index<Content, Metadata>("movies");

await index.upsert({
  id: "document-id",
  content: { title: "Star Wars", genre: "sci-fi" },
  metadata: { year: 1977 }
})
Passing a Content type at the index level will provide type safety for the content coming back from or required for the following commands:
  • search
  • upsert
  • fetch
  • range
In cases you don’t want to define a content type at the index level, you can override the index level type definition for a specific command: 
const results = await index.upsert<Content>({
  id: "id",
  content: { title: "Movie title", ... }
});

​
Telemetry

This sdk sends anonymous telemetry data to help us improve your experience. We collect the following:
  • SDK version
  • Platform (Cloudflare, AWS or Vercel)
  • Runtime version (node@18.x)
You can opt out by setting the UPSTASH_DISABLE_TELEMETRY environment variable to any truthy value. 
UPSTASH_DISABLE_TELEMETRY=1
Alternatively, you can disable telemetry programmatically: 
const index = client.index("movies", {
  enableTelemetry: false,
});
⌘I