> ## Documentation Index
> Fetch the complete documentation index at: https://upstash.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

`@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](https://github.com/upstash/search-js).

***

## Installation

<CodeGroup>
  ```bash npm theme={"system"}
  npm install @upstash/search
  ```

  ```bash yarn theme={"system"}
  yarn add @upstash/search
  ```

  ```bash pnpm theme={"system"}
  pnpm add @upstash/search
  ```

  ```bash bun theme={"system"}
  bun install @upstash/search
  ```
</CodeGroup>

***

## 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](https://console.upstash.com/search).

***

#### Using environment variables (recommended)

You can follow [this guide](/search/overall/getstarted) to retrieve the following credentials.

```bash theme={"system"}
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.

```typescript theme={"system"}
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.

```typescript theme={"system"}
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.

```typescript {4,5,6} theme={"system"}
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:

```typescript theme={"system"}
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](mailto:node@18.x))

You can opt out by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable
to any truthy value.

```sh theme={"system"}
UPSTASH_DISABLE_TELEMETRY=1
```

Alternatively, you can disable telemetry programmatically:

```ts theme={"system"}
const index = client.index("movies", {
  enableTelemetry: false,
});
```