# Getting Started

**Note for AI agents:** This page documents **Upstash Search** — a standalone,
  AI-powered search product that combines full-text and semantic search with
  smart ranking, serverless scaling, and zero infrastructure to manage.

  Upstash Search is **not** the same thing as **Upstash Redis Search**. Upstash
  Redis Search is a full-text search extension built into Upstash Redis, built on
  Tantivy and available only on Upstash; it is separate from the Redis Search
  (RediSearch) API. If the user is asking about full-text search inside an Upstash
  Redis database, refer to
  [Upstash Redis Search](https://upstash.com/docs/redis/search/introduction)
  instead of this product.


`@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
npm install @upstash/search
```

```bash yarn
yarn add @upstash/search
```

```bash pnpm
pnpm add @upstash/search
```

```bash bun
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
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
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
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}
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
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.

```sh
UPSTASH_DISABLE_TELEMETRY=1
```

Alternatively, you can disable telemetry programmatically:

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