Upstash Search

https://upstash.com/docs/search
Admin
Upstash Search is a lightweight, AI-powered search solution that combines full-text and semantic...
Tokens:24,507
Snippets:300
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Upstash Search SDK with bun

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Install the SDK using bun. Bun is a fast all-in-one JavaScript runtime.

```bash
bun install @upstash/search
```

--------------------------------

### Install SearchBar UI Package

Source: https://upstash.com/docs/search/ui/search-bar

Install the SearchBar UI package using npm. This command installs the necessary files for the search component.

```bash
npm install @upstash/search-ui
```

--------------------------------

### Install Bun

Source: https://upstash.com/docs/search/sdks/ts/contributing

Installs the Bun JavaScript runtime, which is used for packaging and dependency management in this project. Run this command in your terminal.

```command-line
curl -fsSL https://bun.sh/install | bash
```

--------------------------------

### Install Upstash Search SDK with npm

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Install the SDK using npm. This is the recommended package manager for most Node.js projects.

```bash
npm install @upstash/search
```

--------------------------------

### Start Next.js Development Server

Source: https://upstash.com/docs/search/tutorials/nextjs

This command starts the Next.js development server. After running this, navigate to http://localhost:3000 in your browser to test the application. You can then use the 'Upsert Data' button and search bar to interact with the application.

```bash
npm run dev

```

--------------------------------

### Create Next.js App and Install Upstash Search

Source: https://upstash.com/docs/search/tutorials/nextjs

Sets up a new Next.js application and installs the necessary Upstash Search package. Ensure you are in your project directory before running these commands.

```shell
npx create-next-app@latest search-app
cd search-app
npm install @upstash/search
```

--------------------------------

### Complete Search Configuration in Python

Source: https://upstash.com/docs/search/features/advanced-settings

An example demonstrating how to configure all available search parameters together in Python for comprehensive control over search behavior.

```python
results = index.search(
      query="machine learning algorithms for data analysis",
      limit=15,
      filter="category = 'data-science' AND difficulty_level <= 'intermediate'",
      reranking=True,
      semantic_weight=0.8,
      input_enrichment=True
  )
```

--------------------------------

### Install Upstash Search Packages

Source: https://upstash.com/docs/search/tutorials/buildsearchbar

Install the necessary Upstash Search and UI packages for your Next.js application.

```shell
npx create-next-app@latest search-docs-app
cd search-docs-app
npm install @upstash/search @upstash/search-ui lucide-react
```

--------------------------------

### Install upstash-search SDK

Source: https://upstash.com/docs/search/sdks/py/gettingstarted

Install the Python SDK using pip. This is the first step to using Upstash Search in your Python application.

```bash
pip install upstash-search
```

--------------------------------

### Install Upstash Search SDK with yarn

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Install the SDK using yarn. Yarn is another popular package manager for JavaScript.

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

--------------------------------

### Complete Search Configuration in TypeScript

Source: https://upstash.com/docs/search/features/advanced-settings

An example demonstrating how to configure all available search parameters together in TypeScript for comprehensive control over search behavior.

```typescript
const results = await index.search({
    query: "machine learning algorithms for data analysis",
    limit: 15,
    filter: "category = 'data-science' AND difficulty_level <= 'intermediate'",
    reranking: true,
    semanticWeight: 0.8,
    inputEnrichment: true
  });
```

--------------------------------

### Install Upstash Search SDK with pnpm

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Install the SDK using pnpm. pnpm is a performant package manager that saves disk space.

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

--------------------------------

### Run CLI Tool

Source: https://upstash.com/docs/search/tools/documentationcrawler

Execute the Upstash Search Crawler CLI tool directly using npx. No installation is required.

```sh
npx @upstash/search-crawler
```

--------------------------------

### Install Docusaurus Upstash Search Theme

Source: https://upstash.com/docs/search/integrations/docusaurus

Install the necessary package for Docusaurus integration. This command should be run in your project's root directory.

```bash
npm install @upstash/docusaurus-theme-upstash-search
```

--------------------------------

### Library Usage Example

Source: https://upstash.com/docs/search/tools/documentationcrawler

Use the Upstash Search Crawler as a library in your TypeScript project. Import the 'crawlAndIndex' function and configure options.

```typescript
import {
  crawlAndIndex,
  type CrawlerOptions,
  type CrawlerResult,
} from "@upstash/search-crawler";

const options: CrawlerOptions = {
  upstashUrl: "UPSTASH_SEARCH_REST_URL",
  upstashToken: "UPSTASH_SEARCH_REST_TOKEN",
  indexName: "my-docs",
  docUrl: "https://example.com/docs",
  silent: true, // no console output
};

const result: CrawlerResult = await crawlAndIndex(options);
```

--------------------------------

### Boolean Operator Precedence Example

Source: https://upstash.com/docs/search/features/filtering

Illustrates the default precedence where AND is evaluated before OR in ambiguous filters without parentheses.

```SQL
country = 'Turkey' AND population > 10000000 OR is_capital = false
```

```SQL
(country = 'Turkey' AND population > 10000000) OR is_capital = false
```

--------------------------------

### Upsert Document with Content and Metadata (Python)

Source: https://upstash.com/docs/search/features/content-and-metadata

Example of upserting a document with both 'content' and 'metadata' fields using Python. 'content' is searchable, while 'metadata' provides context but is not indexed.

```python
index.upsert(
  documents=[
    {
      "id": "star-wars",
      "content": { "text": "Star Wars is a sci-fi space opera."},
      "metadata": {
        "genre": "sci-fi",
      }
    }
  ]
)
```

--------------------------------

### Search with Filter Applied

Source: https://upstash.com/docs/search/sdks/py/commands/search

Narrow down search results by applying a filter based on document fields. This example filters for documents where the category is 'classic'.

```python
results = index.search(
    query="space", 
    limit=2, 
    filter="category = 'classic'"
)
print(results)
```

--------------------------------

### Upsert Document with Content (Python)

Source: https://upstash.com/docs/search/features/content-and-metadata

Example of upserting a document with only the required 'content' field using Python. The 'content' field includes searchable text.

```python
index.upsert(
  documents=[
    {
      "id": "star-wars",
      "content": { "text": "Star Wars is a sci-fi space opera."}
    }
  ]
)
```

--------------------------------

### React SearchBar with Upstash Search Integration

Source: https://upstash.com/docs/search/ui/search-bar

Example of a React SearchBar component integrated with Upstash Search. It demonstrates initializing the search client, defining an index, and using SearchBar components for input, results, and display.

```tsx
"use client"

import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"

import { Search } from "@upstash/search"
import { FileText } from "lucide-react"

const client = new Search({
  url: "<UPSTASH_SEARCH_URL>",
  token: "<YOUR_SEARCH_READONLY_TOKEN>",
})

// 👇 your search index name
const index = client.index<{ title: string }>("movies")

export default function Page() {
  return (
    <div className="max-w-sm mt-24 mx-auto">
      <SearchBar.Dialog>
        <SearchBar.DialogTrigger placeholder="Search movies..." />

        <SearchBar.DialogContent>
          <SearchBar.Input placeholder="Type to search movies..." />
          <SearchBar.Results
            searchFn={(query) => {
              // 👇 100% type-safe: whatever you return here is
              // automatically typed as `result` below
              return index.search({ query, limit: 10, reranking: true })
            }}>
            {(result) => (
              <SearchBar.Result value={result.id} key={result.id}>
                <SearchBar.ResultIcon>
                  <FileText className="text-gray-600" />
                </SearchBar.ResultIcon>

                <SearchBar.ResultContent>
                  <SearchBar.ResultTitle>
                    {result.content.title}
                  </SearchBar.ResultTitle>
                  <p className="text-xs text-gray-500 mt-0.5">Movie</p>
                </SearchBar.ResultContent>
              </SearchBar.Result>
            )}
          </SearchBar.Results>
        </SearchBar.DialogContent>
      </SearchBar.Dialog>
    </div>
  )
}
```

--------------------------------

### Get Database Info

Source: https://upstash.com/docs/search/sdks/ts/commands/info

Retrieve overall database statistics, including disk size and information for all indexes within the database. Use this for a comprehensive overview of your Upstash Search instance.

```typescript
const client = new Search();

const infoResponse = await client.info();
/*
{
  diskSize: 456890
  pendingDocumentCount: 12,
  documentCount: 120,
  indexes: {
    "movies": {
      documentCount: 100,
      pendingDocumentCount: 5
    },
    "actors": {
      documentCount: 20,
      pendingDocumentCount: 7
    }
  }
}
*/
```

--------------------------------

### Upsert Document with Content and Metadata (TypeScript)

Source: https://upstash.com/docs/search/features/content-and-metadata

Example of upserting a document with 'content' and 'metadata' using TypeScript. Metadata like 'director' is included for retrieval but not for searching.

```typescript
await index.upsert([
  {
    id: "star-wars",
    content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
    metadata: { director: "George Lucas" } ,
  }
]);
```

--------------------------------

### List All Active Indexes

Source: https://upstash.com/docs/search/features/indexes

Retrieves the names of all active indexes within the current database. Use this to get an overview of your database's index structure.

```python
client.list_indexes()
```

--------------------------------

### List All Active Indexes

Source: https://upstash.com/docs/search/features/indexes

Retrieves the names of all active indexes within the current database. Use this to get an overview of your database's index structure.

```typescript
await client.listIndexes()
```

--------------------------------

### Upsert Document with Content (TypeScript)

Source: https://upstash.com/docs/search/features/content-and-metadata

Example of upserting a document with 'content' fields like title, genre, and category using TypeScript. These fields are indexed for search.

```typescript
await index.upsert([
  {
    id: "star-wars",
    content: { title: "Star Wars", genre: "sci-fi", category: "classic" }
  }
]);
```

--------------------------------

### Get Index Info

Source: https://upstash.com/docs/search/sdks/ts/commands/info

Retrieve statistics for a specific Upstash Search index, including document counts. Use this when you need to check the status of a single index.

```typescript
const client = new Search();
const index = client.index("movies");

const infoResponse = await index.info();
/*
{ 
  documentCount: 100,
  pendingDocumentCount: 5,
}
*/
```

--------------------------------

### Create and Use an Index

Source: https://upstash.com/docs/search/features/indexes

This snippet demonstrates how to implicitly create an index named 'foo' by performing an upsert operation on it. It also shows how to search within that specific index. Use this when you need to ensure an index exists and perform operations on it.

```python
index = client.index("foo")
index.upsert( ... )
```

--------------------------------

### Initialize Search Client from Environment Variables

Source: https://upstash.com/docs/search/sdks/py/gettingstarted

Configure the Upstash Search client by setting REST URL and Token environment variables. The client can then be initialized without arguments.

```bash
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```

```python
from upstash_search import Search

client = Search.from_env()
```

--------------------------------

### Initialize Upstash Search Client with Environment Variables

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Initialize the Upstash Search client using environment variables for URL and token. This is the recommended approach for most use cases.

```bash
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```

```typescript
import { Search } from "@upstash/search";

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

--------------------------------

### Run CLI Tool with Options

Source: https://upstash.com/docs/search/tools/documentationcrawler

Run the Upstash Search Crawler CLI with specific command-line options for Upstash Search URL, token, index name, and documentation URL.

```sh
npx @upstash/search-crawler \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --index-name "my-index" \
  --doc-url "https://example.com/docs"
```

--------------------------------

### Run the Documentation Indexing Script

Source: https://upstash.com/docs/search/integrations/docusaurus

Execute the command to index your documentation files using the configured environment variables. This script processes files from the specified DOCS_PATH.

```bash
npx index-docs-upstash
```

--------------------------------

### Initialize Search Client with Configuration Object

Source: https://upstash.com/docs/search/sdks/py/gettingstarted

Initialize the Upstash Search client by passing the REST URL and Token directly in the constructor. This is useful for applications interacting with multiple databases.

```python
from upstash_search import Search

client = Search(
    url="<SEARCH_INDEX_REST_URL>",
    token="<SEARCH_INDEX_REST_TOKEN>",
)
```

--------------------------------

### Initialize Upstash Search Client with Configuration Object

Source: https://upstash.com/docs/search/sdks/ts/getting-started

Initialize the Upstash Search client by passing a configuration object with URL and token. This is useful for applications interacting with multiple databases.

```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")
```

--------------------------------

### Basic Search with Python SDK

Source: https://upstash.com/docs/search/sdks/py/commands/search

Perform a basic search query to retrieve relevant documents. Specify the search query and the desired limit for results.

```python
results = index.search(
    query="space opera",
    limit=2
)
print(results)
```

--------------------------------

### Delete Documents by Prefix (TypeScript)

Source: https://upstash.com/docs/search/sdks/py/commands/delete

Use this snippet to delete multiple documents by specifying a common prefix for their IDs. All documents with IDs starting with this prefix will be removed.

```typescript
index.delete(prefix="star-");
```

--------------------------------

### Set Up Environment Variables for Indexing

Source: https://upstash.com/docs/search/integrations/docusaurus

Define environment variables required for the indexing script. Use your Upstash Console credentials, ensuring you use the non-read-only token for indexing.

```bash
UPSTASH_SEARCH_REST_URL=
UPSTASH_SEARCH_REST_TOKEN=
UPSTASH_SEARCH_INDEX_NAME=
DOCS_PATH=
```

--------------------------------

### Run Database Migrator with npx

Source: https://upstash.com/docs/search/tools/databasemigrator

Execute the database migrator tool using npx. This command will prompt for necessary credentials interactively.

```sh
npx @upstash/search-migrator
```

--------------------------------

### E-commerce Product Structure (JavaScript)

Source: https://upstash.com/docs/search/features/content-and-metadata

Illustrates structuring an e-commerce product with searchable 'content' fields (name, description, brand, category) and non-searchable 'metadata' for reference (sku, location, supplier).

```javascript
{
  // 👇 searchable and filterable
  content: {
    name: "Wireless Headphones",
    description: "Noise-cancelling bluetooth headphones", 
    brand: "Sony",
    category: "Electronics"
  },
  // 👇 not searchable, for reference only
  metadata: {
    sku: "AT-WH-001",
    warehouse_location: "A3-15",
    supplier_id: "SUP-123"
  }
}
```

--------------------------------

### Format Code

Source: https://upstash.com/docs/search/sdks/ts/contributing

Formats the project's code according to the defined style guidelines using Bun. This command ensures code consistency across the project.

```bash
bun run fmt
```

--------------------------------

### Handling Search Results with onSelect

Source: https://upstash.com/docs/search/ui/search-bar

Demonstrates how to perform actions when a search result is selected using the `onSelect` prop on `SearchBar.Result`. This allows for custom event handling for each selected item.

```tsx
<SearchBar.Result
  onSelect={() => {
    // 👇 do something with result
    console.log(result)
  }}
  value={result.id}
  key={result.id}
>
```

--------------------------------

### Add Documents with Python SDK

Source: https://upstash.com/docs/search/overall/getstarted

Use the Python SDK to upsert documents into a search index. Ensure you have initialized the Search client with your URL and token.

```python
from upstash_search import Search

client = Search(
    url="<UPSTASH_SEARCH_REST_URL>",
    token="<UPSTASH_SEARCH_REST_TOKEN>",
)

index = client.index("movies")

index.upsert(
    documents=[
        {
            "id": "movie-0",
            "content": {
                "title": "Star Wars",
                "overview": "Sci-fi space opera",
                "genre": "sci-fi",
                "category": "classic",
            },
            "metadata": {
                "poster": "https://poster.link/starwars.jpg",
            },
        },
    ],
)
```

--------------------------------

### Customize Search Bar Input Focus Ring

Source: https://upstash.com/docs/search/ui/search-bar

Change the focus ring color of the search input by applying a Tailwind CSS class. This example sets the focus ring to red.

```tsx
<SearchBar.Input
  className="focus:ring-red-500"
  placeholder="Type to search movies..."
/>
```

--------------------------------

### Configure Upstash Search Environment Variables

Source: https://upstash.com/docs/search/tutorials/nextjs

Adds your Upstash Search REST URL and Token to the .env file. These credentials are required for the client to connect to your search database.

```bash
UPSTASH_SEARCH_REST_URL=<YOUR_SEARCH_REST_URL>
UPSTASH_SEARCH_REST_TOKEN=<YOUR_SEARCH_REST_TOKEN>
```

--------------------------------

### Customize Search Result Title Styling

Source: https://upstash.com/docs/search/ui/search-bar

Modify the styling of the search result title, including its font weight and highlight color. This example uses Tailwind CSS classes to achieve a medium font weight and a red decoration for highlighted text.

```tsx
<SearchBar.ResultTitle
  className="font-medium text-gray-900"
  highlightClassName="decoration-red-500 text-red-500"
>
  {result.content.title}
</SearchBar.ResultTitle>
```

--------------------------------

### Run Tests

Source: https://upstash.com/docs/search/sdks/ts/contributing

Executes all tests within the project. Ensure that necessary environment variables are set before running this command.

```bash
bun run test
```

--------------------------------

### Search Database with Python SDK

Source: https://upstash.com/docs/search/overall/getstarted

Perform a search query on the index using the Python SDK. Specify the query string and a limit for the number of results.

```python
scores = index.search( query="space opera", limit=2, )
```

--------------------------------

### Create and Use an Index

Source: https://upstash.com/docs/search/features/indexes

This snippet demonstrates how to implicitly create an index named 'movies' by performing an upsert operation on it. Use this when you need to ensure an index exists and perform operations on it.

```typescript
const index = client.index("movies");
await index.upsert( ... );
```

--------------------------------

### Knowledge Base Article Structure (JavaScript)

Source: https://upstash.com/docs/search/features/content-and-metadata

Shows how to structure a knowledge base article, using 'content' for searchable fields like title and body, and 'metadata' for non-searchable reference data such as author ID and version.

```javascript
{
  // 👇 searchable and filterable
  content: {
    title: "How to Reset Your Password",
    body: "Follow these steps to reset your password...",
    tags: ["password", "security", "account"]
  },
  // 👇 not searchable, for reference only
  metadata: {
    author_id: "usr_123",
    version: 3,
    approved_by: "usr_456",
    view_count: 1523
  }
}
```

--------------------------------

### Range Method

Source: https://upstash.com/docs/search/sdks/ts/commands/range

Retrieves documents in chunks with pagination. The command is stateless and requires all parameters in each request.

```APIDOC
## Range Method

### Description
Retrieves documents in chunks with pagination. This method supports a variety of options to configure the query to your needs. The range command is stateless, meaning you need to pass all of the parameters in each subsequent request.

### Arguments
#### Path Parameters
- **cursor** (string) - Required - The cursor to the last retrieved document. Should be set to `0` in the initial range request.
- **limit** (number) - Required - The number of maximum documents wanted in the response of range. (page size)
- **prefix** (string) - Optional - A string prefix to match document IDs. All documents with IDs that start with this prefix will be retrieved.

### Response
#### Success Response (200)
- **RangeResponse** (Object) - Required
  - **nextCursor** (string) - The cursor for the next set of documents. When it becomes "", it means all documents were retrieved.
  - **documents** (Document[]) - The list of documents retrieved in this range.

### Request Example
```typescript
// Basic usage
const responseRange = await index.range({
  cursor: "0",
  limit: 2,
});

/*
{ 
  nextCursor: '2',
  documents: [
    { id: "doc1", content: { ... }, metadata: { ... } },
    { id: "doc2", content: { ... }, metadata: { ... } }
  ]
}
*/

// With ID prefix
const responseRangeWithPrefix = await index.range({
  cursor: "0",
  limit: 2,
  prefix: "test-",
});

/*
{ 
  nextCursor: '2',
  documents: [
    { id: "test-1", content: { ... }, metadata: { ... } },
    { id: "test-2", content: { ... }, metadata: { ... } }
  ]
}
*/
```
```

--------------------------------

### Add Documents with TypeScript SDK

Source: https://upstash.com/docs/search/overall/getstarted

Use the TypeScript SDK to upsert documents into a search index. Initialize the Search client with your URL and token.

```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")

await index.upsert([
  {
    id: "star-wars",
    content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
    metadata: { director: "George Lucas" },
  },
])
```

--------------------------------

### Migrate Meilisearch to Upstash using Flags

Source: https://upstash.com/docs/search/tools/databasemigrator

Execute a migration from Meilisearch to Upstash Search by specifying connection details and API keys as command-line flags. This requires your Meilisearch host, API key, and Upstash Search REST URL and Token.

```sh
npx @upstash/search-migrator \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --meilisearch-host "YOUR_MEILISEARCH_HOST" \
  --meilisearch-api-key "YOUR_MEILISEARCH_API_KEY"
```

--------------------------------

### Range Command

Source: https://upstash.com/docs/search/sdks/py/commands/range

Retrieves documents in chunks using pagination. The initial request should have an empty cursor, and subsequent requests use the `next_cursor` from the previous response.

```APIDOC
## Range Command for Python SDK

### Description
The range method is used to retrieve documents in chunks with pagination.

### Arguments
#### Payload (dict, required)
- **cursor** (string, required): The cursor to the last retrieved document. Should be set to `""` in the initial range request.
- **limit** (int, required): The number of maximum documents wanted in the response of range. (page size)

### Response
#### Response (dict, required)
- **Documents** (List[Document], required): This field is `null` if no document with the specified ID is found.
  - **id** (string | number, required): The ID of the resulting document.
  - **content** (Record<string, unknown>): The main content of the document.
  - **metadata** (Record<string, unknown>): Additional metadata for the document.
- **next_cursor** (string): The cursor for the next page of documents.

### Request Example
```python
range_documents = index.range(cursor="", limit=1)
print(range_documents.documents)

range_documents = index.range(
    cursor=range_documents.next_cursor,
    limit=3
)
print(range_documents.documents)
```
```

--------------------------------

### Migrate Algolia to Upstash using Flags

Source: https://upstash.com/docs/search/tools/databasemigrator

Perform a migration from Algolia to Upstash Search by providing credentials and configuration as command-line flags. Ensure you have your Algolia App ID and Write API Key, along with your Upstash Search REST URL and Token.

```sh
npx @upstash/search-migrator \
  --upstash-url "UPSTASH_SEARCH_REST_URL" \
  --upstash-token "UPSTASH_SEARCH_REST_TOKEN" \
  --algolia-app-id "YOUR_ALGOLIA_APP_ID" \
  --algolia-api-key "YOUR_ALGOLIA_WRITE_API_KEY"
```

--------------------------------

### Configure Docusaurus for Upstash Search

Source: https://upstash.com/docs/search/integrations/docusaurus

Add the Upstash Search theme and configure your Upstash credentials in the docusaurus.config.js file. Ensure you use the read-only token for the theme configuration.

```javascript
export default {
  themes: ['@upstash/docusaurus-theme-upstash-search'],
  // ...
  themeConfig: {
    // ...
    upstash: {
      upstashSearchRestUrl: "UPSTASH_SEARCH_REST_URL",
      upstashSearchReadOnlyRestToken: "UPSTASH_SEARCH_READ_ONLY_REST_TOKEN",
      upstashSearchIndexName: "UPSTASH_SEARCH_INDEX_NAME",
    },
  },
};
```

--------------------------------

### News Article Structure (JavaScript)

Source: https://upstash.com/docs/search/features/content-and-metadata

Demonstrates structuring a news article with searchable 'content' (headline, excerpt, category, keywords) and non-searchable 'metadata' for reference (source URL, rights, word count).

```javascript
{
  // 👇 searchable and filterable
  content: {
    headline: "Tech Company Announces New Product",
    excerpt: "In a press conference today...",
    category: "Technology",
    keywords: ["innovation", "product launch"]
  },
  // 👇 not searchable, for reference only
  metadata: {
    source_url: "https://news.example.com/article/123",
    syndication_rights: true,
    word_count: 200
  }
}
```

--------------------------------

### Basic Range Query

Source: https://upstash.com/docs/search/sdks/ts/commands/range

Retrieves documents in chunks with a specified limit. The cursor should be '0' for the initial request. Use this for general pagination.

```typescript
const responseRange = await index.range({
    cursor: "0",
    limit: 2,
  });

  /*
  {
    nextCursor: '2',
    documents: [
      { id: "doc1", content: { ... }, metadata: { ... } },
      { id: "doc2", content: { ... }, metadata: { ... } }
    ]
  }
  */
```

--------------------------------

### Info Command

Source: https://upstash.com/docs/search/sdks/py/commands/info

Retrieves the statistics of an index, including document counts and disk size.

```APIDOC
## Info Command

### Description
Used to retrieve the stats of an index.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
Not applicable (SDK method)

### Request Example
```python
from upstash_search import Search

client = Search(
    url="<UPSTASH_SEARCH_REST_URL>",
    token="<UPSTASH_SEARCH_REST_TOKEN>",
)

info = client.info()
print(info)
```

### Response
#### Success Response
- **document_count** (int) - The total number of documents in the database, that are ready to use.
- **pending_document_count** (int) - The number of documents in the database, that are still processing and not ready to use.
- **disk_size** (int) - Size of the database in bytes.
- **indexes** (dict) - Dictionary of index names and their information (`document_count` and `pending_document_count`)

#### Response Example
```json
{
  "document_count": 1000,
  "pending_document_count": 0,
  "disk_size": 512000,
  "indexes": {
    "my_index": {
      "document_count": 1000,
      "pending_document_count": 0
    }
  }
}
```
```

--------------------------------

### Enable Advanced Reranking (Python)

Source: https://upstash.com/docs/search/features/algorithm

Enable the advanced reranking model for the highest quality results, recommended for applications where search quality is critical. This option incurs an additional cost.

```python
results = index.search(
      query="complex technical documentation",
      reranking=True  # uses premium reranking model
  )
```

--------------------------------

### Retrieve Documents in Chunks with Pagination

Source: https://upstash.com/docs/search/sdks/py/commands/range

Use the range method to fetch documents in paginated chunks. Initialize with an empty cursor and a desired limit. Subsequent calls use the next_cursor from the previous response.

```python
range_documents = index.range(cursor="", limit=1)
print(range_documents.documents)

range_documents = index.range(
    cursor=range_documents.next_cursor,
    limit=3
)
print(range_documents.documents)
```

--------------------------------

### Next.js Home Page with Search Component

Source: https://upstash.com/docs/search/tutorials/buildsearchbar

This snippet shows the main page structure for a Next.js application, including the integration of a custom SearchComponent. It sets up the basic layout and styling for the page.

```typescript
import SearchComponent from "./components/search-bar";

export default function Home() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-50 via-white to-indigo-50">
      <main className="flex-1">
        <div className="max-w-4xl mx-auto px-4 sm:px-6 lg:px-8 pt-20 pb-16">
          <div className="text-center mb-12">
            <h2 className="text-4xl md:text-5xl font-bold text-gray-900 mb-6">
              Search Upstash Documentation
            </h2>
            <p className="text-xl text-gray-600 max-w-2xl mx-auto leading-relaxed">
              Find exactly what you're looking for in our comprehensive documentation.
              Search through guides, APIs, tutorials, and more with lightning-fast results.
            </p>
          </div>
          {/* Search Component */}
          <div className="max-w-2xl mx-auto">
            <SearchComponent />
          </div>
          <div className="mt-20 grid md:grid-cols-3 gap-8">
            <div className="text-center">
              <div className="w-12 h-12 bg-blue-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-blue-600" fill="none" stroke="currentColor" viewBox="0 0 24 24" aria-hidden="true">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M13 10V3L4 14h7v7l9-11h-7z" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Lightning Fast</h3>
              <p className="text-gray-600">Get instant search results powered by advanced indexing</p>
            </div>
            <div className="text-center">
              <div className="w-12 h-12 bg-green-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-green-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M9 12l2 2 4-4m6 2a9 9 0 11-18 0 9 9 0 0118 0z" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Accurate Results</h3>
              <p className="text-gray-600">Reranking ensures the most relevant content appears first</p>
            </div>
            <div className="text-center">
              <div className="w-12 h-12 bg-purple-100 rounded-lg flex items-center justify-center mx-auto mb-4">
                <svg className="w-6 h-6 text-purple-600" fill="none" stroke="currentColor" viewBox="0 0 24 24">
                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2}
                    d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 
                  18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 
                  5c1.746 0 3.332.477 4.5 1.253v13C19.832 18.477 18.246 18 16.5 18c-1.746 
                  0-3.332.477-4.5 1.253" />
                </svg>
              </div>
              <h3 className="text-lg font-semibold text-gray-900 mb-2">Comprehensive</h3>
              <p className="text-gray-600">Search across all documentation, guides, and API references</p>
            </div>
          </div>
        </div>
      </main>
    </div>
  );
}

```

--------------------------------

### Import SearchBar UI and Styles

Source: https://upstash.com/docs/search/ui/search-bar

Import the SearchBar component and its associated CSS styles. This is required to use the component in your React application.

```typescript
// 👇 import package and optimized styles
import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"
```

--------------------------------

### Initialize Search Client with Telemetry Disabled

Source: https://upstash.com/docs/search/sdks/py/gettingstarted

Initialize the Upstash Search client while disabling anonymous telemetry data collection by setting allow_telemetry to False.

```typescript
client = Search(
    url="UPSTASH_SEARCH_REST_URL",
    token="UPSTASH_SEARCH_REST_TOKEN",
    allow_telemetry=False,
)
```

--------------------------------

### Retrieve Index Statistics with Info Command

Source: https://upstash.com/docs/search/sdks/py/commands/info

Use this snippet to fetch the current statistics of your Upstash Search index, including document counts and disk size. Ensure you have initialized the Search client with your Upstash Search REST URL and token.

```python
from upstash_search import Search

client = Search(
    url="<UPSTASH_SEARCH_REST_URL>",
    token="<UPSTASH_SEARCH_REST_TOKEN>",
)

info = client.info()
print(info)
```

--------------------------------

### Upsert Documents to an Index

Source: https://upstash.com/docs/search/sdks/py/gettingstarted

Create an index named 'films' and upsert documents containing title, overview, genre, category, and metadata. Each document requires a unique ID.

```python
index = client.index("films")

index.upsert(
    documents=[
        {
            "id": "movie-0",
            "content": {
                "title": "Star Wars",
                "overview": "Sci-fi space opera",
                "genre": "sci-fi",
                "category": "classic",
            },
            "metadata": {
                "poster": "https://poster.link/starwars.jpg",
            },
        },
    ],
)
```

--------------------------------

### Fetch Documents by ID Prefix

Source: https://upstash.com/docs/search/sdks/ts/commands/fetch

This snippet demonstrates how to fetch documents that share a common ID prefix. It's useful for retrieving a group of related documents.

```typescript
await index.fetch({ prefix: "star-" });
/*
[
  {
    id: "star-wars"
    content: { ... },
    metadata: { ... }
  },
  {
    id: "star-trek",
    content: { ... },
    metadata: { ... }
  }
]
*/
```

--------------------------------

### Fetch Documents by ID Prefix using Python SDK

Source: https://upstash.com/docs/search/sdks/py/commands/fetch

Retrieve documents from Upstash Search that match a specified ID prefix. The 'prefix' argument should be a string representing the desired prefix.

```python
documents = index.fetch(prefix=["movie-"])
print(documents)
```

--------------------------------

### Create Upstash Search Component

Source: https://upstash.com/docs/search/tutorials/buildsearchbar

Implement a React component using Upstash Search UI to provide a search bar and results display. Ensure your index name matches the one used in the crawler.

```typescript
"use client"

import { SearchBar } from "@upstash/search-ui"
import "@upstash/search-ui/dist/index.css"
import { Search } from "@upstash/search"
import { FileText } from "lucide-react"

const client = new Search({
  url: process.env.NEXT_PUBLIC_UPSTASH_SEARCH_URL! ,
  token: process.env.NEXT_PUBLIC_UPSTASH_SEARCH_READONLY_TOKEN!,
})
// 👇 your search index name
const index = client.index<{ title: string }>("default")

export default function SearchComponent() {
  return (
    <div className="max-w-sm mt-24 mx-auto">
      <SearchBar.Dialog>
        <SearchBar.DialogTrigger placeholder="Search..." />

        <SearchBar.DialogContent>
          <SearchBar.Input placeholder="Type to search..." />
          <SearchBar.Results
            searchFn={(query) => {
              // 👇 100% type-safe: whatever you return here is
              // automatically typed as `result` below
              return index.search({ query, limit: 10, reranking: true })
            }}
          >
            {(result) => (
                <div key={result.id} onClick={() => {
                   window.open(result.metadata?.url as string, "_blank")
                 }}>
               <SearchBar.Result 
                 value={result.id} 
                 className="cursor-pointer hover:bg-gray-50 transition-colors duration-200"
               >
                <SearchBar.ResultIcon>
                    <FileText className="text-gray-600" />
                </SearchBar.ResultIcon>

                <SearchBar.ResultContent>
                  <SearchBar.ResultTitle>
                    {result.content.title}
                  </SearchBar.ResultTitle>
                  <p className="text-xs text-gray-500 mt-0.5">Docs</p>
                </SearchBar.ResultContent>
              </SearchBar.Result>
              </div>
            )}
          </SearchBar.Results>
        </SearchBar.DialogContent>
      </SearchBar.Dialog>
    </div>
  )
}
```

--------------------------------

### Search Command for Python SDK

Source: https://upstash.com/docs/search/sdks/py/commands/search

The search method retrieves relevant documents using AI-powered search. It accepts a payload with query, limit, reranking, filter, semantic_weight, and input_enrichment parameters.

```APIDOC
## Search Command for Python SDK

### Description
Retrieves the most relevant documents from the database using AI-powered search capabilities.

### Arguments
#### Payload (dict, required)
- **query** (string, required) - The search query string.
- **limit** (int, required) - The maximum number of results to return. Defaults to 10.
- **reranking** (bool, optional) - Whether to enable AI-powered reranking of results. Disabled by default.
- **filter** (string, optional) - A filter for narrowing down the search results based on content fields.
- **semantic_weight** (number, optional) - Optional relevance balance between semantic and keyword search (0-1 range, defaults to 0.75).
- **input_enrichment** (boolean, optional) - Optional boolean to enhance queries before searching (enabled by default).

### Response
#### Documents (List[DocumentScore], required)
This field is `null` if no document with the specified ID is found.

- **id** (string | number, required) - The ID of the resulting document.
- **content** (Record<string, unknown>, optional) - The main content of the document.
- **metadata** (Record<string, unknown>, optional) - Additional metadata for the document.
- **score** (float, required) - Similarity score of the document

### Request Example
```python
# Basic Search
results = index.search(
    query="space opera",
    limit=2
)
print(results)

# Search with Reranking
results = index.search(
    query="space opera",
    limit=2,
    reranking=True
)
print(results)

# Search with Filter
results = index.search(
    query="space", 
    limit=2, 
    filter="category = 'classic'"
)
print(results)
```
```

--------------------------------

### Range Query with ID Prefix

Source: https://upstash.com/docs/search/sdks/ts/commands/range

Retrieves documents that match a specific ID prefix, in addition to pagination. Useful when document IDs follow a predictable pattern.

```typescript
const responseRange = await index.range({
    cursor: "0",
    limit: 2,
    prefix: "test-",
  });

  /*
  {
    nextCursor: '2',
    documents: [
      { id: "test-1", content: { ... }, metadata: { ... } },
      { id: "test-2", content: { ... }, metadata: { ... } }
    ]
  }
  */
```

--------------------------------

### Fetch Command for Python SDK

Source: https://upstash.com/docs/search/sdks/py/commands/fetch

Retrieves documents by their IDs using the Upstash Search Python SDK. You can fetch specific documents by providing a list of their IDs or retrieve documents matching a given ID prefix.

```APIDOC
## Fetch Command for Python SDK

Used to retrieve documents by their IDs.

### Arguments

#### FetchPayload (object, required)

- **ids** (string[]) - Required - The IDs of the documents you want to fetch.
- **prefix** (string) - Optional - An ID prefix to match document IDs.

### Response

#### Documents (List[Document], required)

This field is `null` if no document with the specified ID is found.

- **id** (string | number, required) - The ID of the resulting document.
- **content** (Record<string, unknown>) - The main content of the document.
- **metadata** (Record<string, unknown>) - Additional metadata for the document.

### Request Example

```python
# Fetch by ID
documents = index.fetch(ids=["movie-0", "movie-1"])
print(documents)

# Fetch by ID Prefix
documents = index.fetch(prefix=["movie-"])
print(documents)
```
```

--------------------------------

### Fetch Documents by ID Prefix

Source: https://upstash.com/docs/search/sdks/ts/commands/fetch

Retrieves documents from the index that match a specified ID prefix. This is useful for fetching a group of related documents.

```APIDOC
## Fetch Documents by ID Prefix

### Description
Retrieves documents from the index that match a specified ID prefix. This is useful for fetching a group of related documents.

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Request Body
- **prefix** (string) - Required - An ID prefix to match document IDs.

### Request Example
```typescript
await index.fetch({ prefix: "star-" });
/*
[
  {
    id: "star-wars"
    content: { ... },
    metadata: { ... }
  },
  {
    id: "star-trek",
    content: { ... },
    metadata: { ... }
  }
]
*/
```

### Response
#### Success Response (200)
- **FetchResult[]** (Document[]) - An array of documents matching the provided ID prefix.
  - **id** (string | number) - Required - The ID of the resulting document.
  - **content** (Record<string, unknown>) - The content of the document.
  - **metadata** (Record<string, unknown>) - The metadata associated with the document.

#### Response Example
```json
[
  {
    "id": "star-wars",
    "content": { ... },
    "metadata": { ... }
  },
  {
    "id": "star-trek",
    "content": { ... },
    "metadata": { ... }
  }
]
```
```

--------------------------------

### Search with Reranking Enabled

Source: https://upstash.com/docs/search/sdks/py/commands/search

Execute a search query with AI-powered reranking enabled to improve result relevance. This requires setting the 'reranking' argument to True.

```python
results = index.search(
    query="space opera",
    limit=2,
    reranking=True
)
print(results)
```

--------------------------------

### Basic Search

Source: https://upstash.com/docs/search/sdks/ts/commands/search

Performs a basic search query with a specified query string and limit. Use this for simple keyword-based retrieval.

```typescript
const searchResults = await index.search({
    query: "space opera",
    limit: 2,
  });
  console.log(searchResults);
```

--------------------------------

### Enable Advanced Reranking

Source: https://upstash.com/docs/search/features/algorithm

Enable the advanced reranking model for the highest quality results, recommended for applications where search quality is critical. This option incurs an additional cost.

```typescript
const results = await index.search({
    query: "complex technical documentation",
    reranking: true // uses premium reranking model
  });
```

--------------------------------

### Fetch Documents by ID using Python SDK

Source: https://upstash.com/docs/search/sdks/py/commands/fetch

Retrieve specific documents from Upstash Search by providing a list of their unique IDs. Ensure the 'ids' argument is a list of strings.

```python
documents = index.fetch(ids=["movie-0", "movie-1"])
print(documents)
```

--------------------------------

### Type-Safe Filtering with Content and Metadata (TypeScript)

Source: https://upstash.com/docs/search/features/filtering

Build filters programmatically using a type-safe approach in TypeScript. Define types for content and metadata to enable robust filtering. Use '@metadata' prefix for metadata fields.

```typescript
import { Search } from "@upstash/search";

type Content = { text: string }
type Metadata = { count: number }

const client = Search.fromEnv()
const searchIndex = client.index<Content, Metadata>("hello world!");

const results = await searchIndex.search({
  query: "hello world!",
  limit: 2,
  filter: {
    AND: [
      // filtering by content field
      { text: { glob: "*test-data*" } }, 
      // filtering by metadata field (add @metadata prefix)
      { "@metadata.count": { greaterThanOrEquals: 3 } }
    ],
  },
});
```

--------------------------------

### Fetch Documents by IDs

Source: https://upstash.com/docs/search/sdks/ts/commands/fetch

Use this snippet to retrieve multiple documents by providing an array of their IDs. The response will be an array of found documents, or null if no documents match.

```typescript
await index.fetch({ ids: ["star-wars", "inception"] });
/*
[
  {
    id: "star-wars",
    content: { ... },
    metadata: { ... }
  },
  {
    id: "inception",
    content: { ... },
    metadata: { ... }
  }
]
*/
```

--------------------------------

### Adjust Hybrid Search Weights (Python)

Source: https://upstash.com/docs/search/features/algorithm

Adjust the balance between semantic and full-text search weights. Higher semantic weight is better for conceptual searches, while lower weight is better for exact keyword matching.

```python
results = index.search(
      query="artificial intelligence concepts",
      semantic_weight=0.9  # 90% semantic, 10% full-text
  )
```

--------------------------------

### Filter by Content and Metadata (Python)

Source: https://upstash.com/docs/search/features/filtering

Filter search results by specifying conditions on both content and metadata fields using a string-based filter. Ensure metadata keys are prefixed with '@metadata'.

```python
scores = index.search(
    query="sony headphones",
    filter="warehouse_location = 'A3-15' AND @metadata.supplier_id = 'SUP-123'",
)
```
Tokens:
Raw