TITLE: Installing Upstash Search SDK
DESCRIPTION: This section provides commands to install the `@upstash/search` SDK using various package managers. Choose the command corresponding to your preferred package manager (npm, yarn, pnpm, or bun) to add the SDK to your project dependencies.
SOURCE: https://upstash.com/docs/search/sdks/ts/getting-started.mdx

LANGUAGE: bash
CODE:
```
npm install @upstash/search
```

LANGUAGE: bash
CODE:
```
yarn add @upstash/search
```

LANGUAGE: bash
CODE:
```
pnpm add @upstash/search
```

LANGUAGE: bash
CODE:
```
bun install @upstash/search
```

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

TITLE: Installing Upstash Search SDK - Bash
DESCRIPTION: This snippet demonstrates how to install the `upstash-search` Python SDK using pip, the package installer for Python. This is the first step to integrate Upstash AI Search capabilities into your Python projects.
SOURCE: https://upstash.com/docs/search/sdks/py/gettingstarted.mdx

LANGUAGE: bash
CODE:
```
pip install upstash-search
```

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

TITLE: Adding Documents to Upstash Search Index (Python)
DESCRIPTION: This snippet demonstrates how to initialize the Upstash Search client and upsert documents into an index using the Python SDK. It requires the `upstash_search` library and uses a REST URL and token for authentication. Documents are provided as a list of dictionaries, each with an `id`, `content` (searchable data), and optional `metadata`.
SOURCE: https://upstash.com/docs/search/overall/getstarted.mdx

LANGUAGE: python
CODE:
```
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",
            },
        },
    ],
)
```

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

TITLE: Initializing Upstash Search Client from Environment Variables - Python
DESCRIPTION: This snippet shows how to initialize the `Search` client by reading configuration from environment variables. It requires `UPSTASH_SEARCH_REST_URL` and `UPSTASH_SEARCH_REST_TOKEN` to be set, providing a convenient way to manage credentials without hardcoding them.
SOURCE: https://upstash.com/docs/search/sdks/py/gettingstarted.mdx

LANGUAGE: bash
CODE:
```
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```

LANGUAGE: python
CODE:
```
from upstash_search import Search

client = Search.from_env()
```

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

TITLE: Initializing Upstash Search Client with Environment Variables - Bash & TypeScript
DESCRIPTION: This method demonstrates initializing the Upstash Search client by setting REST URL and token as environment variables. The client then automatically picks up these credentials, simplifying configuration for applications interacting with a single database.
SOURCE: https://upstash.com/docs/search/sdks/ts/getting-started.mdx

LANGUAGE: bash
CODE:
```
UPSTASH_SEARCH_REST_URL="your_rest_url"
UPSTASH_SEARCH_REST_TOKEN="your_rest_token"
```

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

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

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

TITLE: Searching Upstash Search Index (TypeScript)
DESCRIPTION: This snippet demonstrates how to execute a search query against an Upstash Search index using the TypeScript SDK. It invokes the `search` method on an `index` object, passing an object with a `query` string, an optional `limit` for results, and a `reranking` flag. The method returns an array of search results.
SOURCE: https://upstash.com/docs/search/overall/getstarted.mdx

LANGUAGE: typescript
CODE:
```
const searchResults = await index.search({
  query: "space opera",
  limit: 2,
  reranking: true,
});
```

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

TITLE: Searching Upstash Search Index (Python)
DESCRIPTION: This snippet shows how to perform a search query on an Upstash Search index using the Python SDK. It calls the `search` method on an `index` object, providing a `query` string and an optional `limit` for the number of results. The method returns search results, typically including scores.
SOURCE: https://upstash.com/docs/search/overall/getstarted.mdx

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

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

TITLE: Upserting a Single Document with Upsert Search (TypeScript)
DESCRIPTION: This snippet demonstrates how to add a single new document to the Upsert Search index. It requires an 'id', a 'content' object for searchable fields, and an optional 'metadata' object for additional attributes. The operation returns 'Success' on completion.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/upsert.mdx

LANGUAGE: typescript
CODE:
```
await index.upsert({
  id: "star-wars",
  content: { title: "Star Wars", genre: "sci-fi" },
  metadata: { year: 1977 }
});
```

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

TITLE: Upserting Documents with Upstash Search Python SDK
DESCRIPTION: This snippet demonstrates how to use the `upsert` command in the Upstash Search Python SDK to add or update documents. It initializes a `Search` client with a URL and token, selects an index, and then calls `upsert` with a list of documents, each containing an `id`, `content` (with `title`, `overview`, `genre`, `category`), and optional `metadata` (with `poster`).
SOURCE: https://upstash.com/docs/search/sdks/py/commands/upsert.mdx

LANGUAGE: python
CODE:
```
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",
            },
        },
    ],
)
```

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

TITLE: Updating an Existing Document with Upsert Search (TypeScript)
DESCRIPTION: This snippet shows how to update an existing document in the Upsert Search index. By providing an 'id' that already exists, the 'content' and 'metadata' fields of that document will be updated. Only the specified fields are updated, others remain unchanged.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/upsert.mdx

LANGUAGE: typescript
CODE:
```
await index.upsert({
  id: "star-wars",
  content: {
    title: "Star Wars: Episode IV - A New Hope",
    genre: "sci-fi"
  },
});
```

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

TITLE: Upserting Documents with Searchable Content - TypeScript
DESCRIPTION: This snippet demonstrates how to upsert a document using the `content` field in TypeScript. The `content` field is required and its data is indexed, making it searchable and filterable for queries.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

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

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

TITLE: Performing Search with Filtering using Upstash Search (TypeScript)
DESCRIPTION: This snippet illustrates how to apply a filter to narrow down search results. It searches for 'space', limits results to 2, and filters documents where the 'category' field equals 'classic', then logs the results.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/search.mdx

LANGUAGE: typescript
CODE:
```
const searchResults = await index.search({
  query: "space",
  limit: 2,
  filter: "category = 'classic'",
});
console.log(searchResults);
```

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

TITLE: Performing Search with Filtering in Upstash Search Python SDK
DESCRIPTION: This snippet illustrates how to apply a filter to search results using the `index.search` method. It queries for "space", limits results to 2, and uses a `filter` string to narrow down documents where the 'category' field equals 'classic'. The filtered results are then printed.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/search.mdx

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

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

TITLE: Adding Documents to Upstash Search Index (TypeScript)
DESCRIPTION: This snippet illustrates how to initialize the Upstash Search client and upsert documents into an index using the TypeScript SDK. It imports `Search` from `@upstash/search` and authenticates with a REST URL and token. Documents are provided as an array of objects, each containing an `id`, `content` (searchable data), and optional `metadata`.
SOURCE: https://upstash.com/docs/search/overall/getstarted.mdx

LANGUAGE: typescript
CODE:
```
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" },
  },
])
```

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

TITLE: Deleting a Single Document by ID in Upstash Search (TypeScript)
DESCRIPTION: This snippet illustrates how to delete a single document from an Upstash Search index using its unique ID. It performs an asynchronous deletion and shows the response indicating one document was deleted.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/delete.mdx

LANGUAGE: TypeScript
CODE:
```
const response = await index.delete("star-wars");
// { deleted: 1 }
```

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

TITLE: Configuring Upstash Search Environment Variables (Bash)
DESCRIPTION: This snippet shows how to add the Upstash Search REST URL and Token to your project's `.env` file. These environment variables are crucial for authenticating and connecting your Next.js application to your Upstash Search database, ensuring secure access to your search index.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

LANGUAGE: bash
CODE:
```
UPSTASH_SEARCH_REST_URL=<YOUR_SEARCH_REST_URL>
UPSTASH_SEARCH_REST_TOKEN=<YOUR_SEARCH_REST_TOKEN>
```

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

TITLE: Performing Basic Search using Upstash Search (TypeScript)
DESCRIPTION: This snippet demonstrates how to perform a basic search query using the `index.search` method. It searches for 'space opera' and limits the results to 2, then logs the results to the console.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/search.mdx

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

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

TITLE: Creating a Search Page with React and Upstash Search (TypeScript)
DESCRIPTION: This TypeScript code defines the main frontend page (`app/page.tsx`) for a search application. It uses React's `useState` hook to manage search results, query input, and UI states for data upsertion. The page interacts with `/api/upsert` and `/api/search` endpoints to manage and retrieve data, displaying results in a list.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

LANGUAGE: typescript
CODE:
```
"use client";

import { useState } from "react";

interface SearchResult {
  id: string;
  content: Record<string, unknown>;
  metadata: Record<string, unknown>;
  score: number;
}

export default function Home() {
  const [searchResults, setSearchResults] = useState<SearchResult[]>([]);
  const [query, setQuery] = useState("");
  const [isUpserting, setIsUpserting] = useState(false);
  const [upsertSuccess, setUpsertSuccess] = useState(false);

  const upsertData = async () => {
    setIsUpserting(true);
    setUpsertSuccess(false);
    await fetch("/api/upsert", { method: "POST" });
    setIsUpserting(false);
    setUpsertSuccess(true);
  };

  const search = async () => {
    const res = await fetch(`/api/search`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ query }),
    });
    const data = await res.json();
    setSearchResults(data || []);
  };

  return (
    <main className="min-h-screen bg-emerald-50 flex flex-col items-center py-10">
      <div className="w-full max-w-2xl bg-white shadow-md rounded-lg p-6">
        <header className="mb-6 text-center">
          <h1 className="text-2xl font-bold text-emerald-800">Search App</h1>
          <p className="text-emerald-600">
            Upsert data and search through the database.
          </p>
        </header>

        <div className="mb-6">
          <button
            onClick={upsertData}
            disabled={isUpserting}
            className={`w-full py-2 px-4 rounded-md text-white ${
              isUpserting
                ? "bg-emerald-300"
                : "bg-emerald-500 hover:bg-emerald-600"
            }`}
          >
            {isUpserting ? "Upserting..." : "Upsert Data"}
          </button>
          {upsertSuccess && (
            <p className="mt-2 text-sm text-emerald-600">
              Data upserted successfully!
            </p>
          )}
        </div>

        <div className="mb-6">
          <div className="flex gap-2">
            <input
              type="text"
              value={query}
              onChange={(e) => setQuery(e.target.value)}
              placeholder="Search..."
              className="flex-1 border border-emerald-300 rounded-md px-4 py-2 text-gray-800 focus:outline-none focus:ring-2 focus:ring-emerald-500"
            />
            <button
              onClick={search}
              className="bg-emerald-500 text-white px-4 py-2 rounded-md hover:bg-emerald-600"
            >
              Search
            </button>
          </div>
        </div>

        <ul className="space-y-2">
          {searchResults.map((result, index) => (
            <li
              key={index}
              className="bg-emerald-100 p-4 rounded-md shadow-sm text-emerald-800"
            >
              <p className="font-bold">ID: {result.id}</p>
              <p className="text-sm">Content: {JSON.stringify(result.content)}</p>
              <p className="text-sm">Metadata: {JSON.stringify(result.metadata)}</p>
              <p className="text-sm">Score: {result.score}</p>
            </li>
          ))}
        </ul>
      </div>
    </main>
  );
}
```

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

TITLE: Performing Basic Search with Upstash Search Python SDK
DESCRIPTION: This snippet demonstrates a basic search operation using the `index.search` method in the Upstash Search Python SDK. It queries for "space opera" and limits the results to 2, without enabling reranking or filtering. The retrieved results are then printed to the console.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/search.mdx

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

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

TITLE: Performing Search with AI-powered Reranking in Upstash Search Python SDK
DESCRIPTION: This snippet shows how to perform a search with AI-powered reranking enabled using the `index.search` method. It queries for "space opera", limits results to 2, and sets `reranking` to `True` to improve the relevance of the search results. The reranked results are then printed.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/search.mdx

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

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

TITLE: Performing Search with AI Reranking using Upstash Search (TypeScript)
DESCRIPTION: This snippet shows how to enable AI-powered reranking for search results. It queries for 'space opera', limits results to 2, and sets `reranking` to `true` to improve relevance, then logs the results.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/search.mdx

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

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

TITLE: Performing Search with Reranking in Python
DESCRIPTION: This snippet demonstrates how to perform a search query using the Upstash Search index in Python, enabling the re-ranking feature. The `reranking=True` parameter ensures that the returned documents are further processed by a state-of-the-art model for improved relevancy, with a limit of 2 results.
SOURCE: https://upstash.com/docs/search/features/reranking.mdx

LANGUAGE: python
CODE:
```
scores = index.search(
    query="space opera",
    limit=2,
    reranking=True,
)
```

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

TITLE: Creating Next.js API Route to Upsert Documents with Upstash Search (TypeScript)
DESCRIPTION: This TypeScript snippet defines a Next.js API route (`app/api/upsert/route.ts`) responsible for adding or updating documents in an Upstash Search index. It initializes the Upstash Search client using environment variables and then uses the `index.upsert` method to store sample movie data, including `id`, `content`, and `metadata` fields.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

LANGUAGE: typescript
CODE:
```
import { Search } from "@upstash/search"

const client = new Search({
  url: process.env.UPSTASH_SEARCH_REST_URL,
  token: process.env.UPSTASH_SEARCH_REST_TOKEN,
})

const index = client.index("my-index")

export async function POST() {
  await index.upsert([
    {
      id: "movie-1",
      content: {
        title: "Inception",
        description: "A thriller about dreams within dreams.",
      },
      metadata: { genre: "sci-fi", year: 2010 },
    },
    {
      id: "movie-2",
      content: {
        title: "The Godfather",
        description: "A story about a powerful Italian-American crime family.",
      },
      metadata: { genre: "crime", year: 1972 },
    },
    {
      id: "movie-3",
      content: {
        title: "The Dark Knight",
        description: "A tale of Batman's fight against the Joker.",
      },
      metadata: { genre: "action", year: 2008 },
    },
  ])

  return new Response("OK")
}
```

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

TITLE: Understanding AND/OR Precedence in SQL
DESCRIPTION: This snippet illustrates the default precedence where `AND` has higher precedence than `OR` when no parentheses are provided. The `AND` operation is evaluated before the `OR` operation.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

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

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

TITLE: Creating Next.js API Route to Search Documents with Upstash Search (TypeScript)
DESCRIPTION: This TypeScript snippet illustrates a Next.js API route (`app/api/search/route.ts`) designed to handle search queries against the Upstash Search index. It initializes the Upstash Search client, extracts a `query` string from the incoming `POST` request body, executes the search using `index.search`, and returns the results as a JSON response.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

LANGUAGE: typescript
CODE:
```
import { Search } from "@upstash/search"

const client = new Search({
  url: process.env.UPSTASH_SEARCH_REST_URL,
  token: process.env.UPSTASH_SEARCH_REST_TOKEN,
})

const index = client.index("my-index")

export async function POST(req: Request) {
  const { query } = (await req.json()) as { query: string }

  const results = await index.search({ query })

  return new Response(JSON.stringify(results))
}
```

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

TITLE: Grouping Boolean Operators with Parentheses in SQL
DESCRIPTION: This example shows how to group boolean operators using parentheses to control precedence. Conditions within parentheses are evaluated first, allowing for complex logical combinations.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

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

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

TITLE: Defining Content and Metadata Types for Upstash Search Index - TypeScript
DESCRIPTION: This snippet illustrates how to define custom TypeScript types for content and metadata at the index level, providing complete type-safety for operations like `search`, `upsert`, `fetch`, and `range`. This ensures data consistency and improves developer experience.
SOURCE: https://upstash.com/docs/search/sdks/ts/getting-started.mdx

LANGUAGE: typescript
CODE:
```
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 }
})
```

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

TITLE: News Article Document Structure Example - JavaScript
DESCRIPTION: This example illustrates the document structure for news articles. Searchable information like headline, excerpt, category, and keywords are placed in `content`, while non-searchable details such as source URL, syndication rights, and word count are stored in `metadata`.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

LANGUAGE: JavaScript
CODE:
```
{
  // 👇 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
  }
}
```

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

TITLE: Performing Search with Reranking in TypeScript
DESCRIPTION: This snippet illustrates how to execute a search query against the Upstash Search index in TypeScript, activating the re-ranking capability. By setting `reranking: true`, the search results will undergo additional processing by an advanced model to enhance relevancy, retrieving up to 2 documents.
SOURCE: https://upstash.com/docs/search/features/reranking.mdx

LANGUAGE: ts
CODE:
```
const searchResults = await index.search({
  query: "space opera",
  limit: 2,
  reranking: true,
});
```

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

TITLE: Semantic Equivalent of In Operator in SQL Filter Syntax
DESCRIPTION: This SQL-like filter syntax shows the semantic equivalent of the `in` operator, using multiple `equals` operations combined with the `OR` boolean operator. It filters for documents where `country` is 'Germany' OR 'Turkey' OR 'France'. This clarifies how the `in` operator simplifies complex `OR` conditions.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
country = 'Germany' OR country = 'Turkey' OR country = 'France'
```

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

TITLE: Defining Searchable Content Structure in TypeScript
DESCRIPTION: This TypeScript snippet illustrates the structure of a document's content and metadata for Upstash Search. The `content` object contains searchable and filterable keys like `name`, `description`, `brand`, `category`, `warehouse_location`, and `in_stock`. The `metadata` object holds non-searchable reference data such as `sku` and `supplier_id`.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

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

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

TITLE: Upserting Multiple Documents with Upsert Search (TypeScript)
DESCRIPTION: This snippet illustrates how to add or update multiple documents simultaneously in the Upsert Search index. It takes an array of document objects, each requiring an 'id', 'content', and optional 'metadata'. This batch operation efficiently handles multiple document entries.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/upsert.mdx

LANGUAGE: typescript
CODE:
```
await index.upsert([
  {
    id: "inception",
    content: { title: "Inception", genre: "action" }
    metadata: {
      year: 2010,
    },
  },
  { ... },
]);
```

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

TITLE: Using Greater Than or Equals Operator in SQL Filter Syntax
DESCRIPTION: This SQL-like filter syntax demonstrates the `greater than or equals` operator (`>=`) to filter content where a numeric value is greater than or equal to a given literal. It filters for documents where `in_stock` is greater than or equal to 3. This operator is applicable only to number values.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
in_stock >= 3
```

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

TITLE: Using Less Than or Equals Operator in SQL Filter Syntax
DESCRIPTION: This SQL-like filter syntax demonstrates the `less than or equals` operator (`<=`) to filter content where a numeric value is less than or equal to a given literal. It filters for documents where `in_stock` is less than or equal to 3. This operator is applicable only to number values.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
in_stock <= 3
```

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

TITLE: Using Not Equals Operator in SQL Filter Syntax
DESCRIPTION: This SQL-like filter syntax demonstrates the `not equals` operator (`!=`) to exclude content keys with specific literal values. It filters for documents where `warehouse_location` is NOT 'A3-15' AND `in_stock` is NOT 3. This operator is applicable to string, number, and boolean values.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
warehouse_location != 'A3-15' AND in_stock != 3
```

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

TITLE: Filtering Search Results in TypeScript
DESCRIPTION: This TypeScript snippet shows how to execute a search query with a filter using the Upstash Search index. It queries for 'sony headphones' and restricts results to documents where `warehouse_location` matches 'A3-15'. The `searchResults` constant will contain the filtered documents.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: TypeScript
CODE:
```
const searchResults = await index.search({
    query: "sony headphones",
    filter: "warehouse_location = 'A3-15'",
});
```

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

TITLE: Filtering Nested Object Fields in SQL
DESCRIPTION: This snippet demonstrates filtering nested object fields using the `.` accessor. Fields can be referenced at arbitrary depths to target specific properties within complex JSON structures.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
economy.currency != 'USD' AND geography.coordinates.latitude >= 35.0
```

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

TITLE: E-commerce Product Document Structure Example - JavaScript
DESCRIPTION: This example illustrates the recommended document structure for e-commerce products. Searchable details like name, description, brand, and category are placed in `content`, while non-searchable reference data such as SKU, warehouse location, and supplier ID are stored in `metadata`.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

LANGUAGE: JavaScript
CODE:
```
{
  // 👇 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"
  }
}
```

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

TITLE: Upserting Documents to an Upstash Search Index - Python
DESCRIPTION: This snippet demonstrates how to obtain an index instance from the `Search` client and upsert documents into it. Documents are provided as a list of dictionaries, each containing an `id`, `content` (for search), and optional `metadata`.
SOURCE: https://upstash.com/docs/search/sdks/py/gettingstarted.mdx

LANGUAGE: python
CODE:
```
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"
            }
        }
    ]
)
```

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

TITLE: Filtering Search Results in Python
DESCRIPTION: This Python snippet demonstrates how to perform a search query with a filter using the Upstash Search index. It searches for 'sony headphones' and applies a filter to only return documents where `warehouse_location` is exactly 'A3-15'. The `scores` variable will hold the filtered search results.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: Python
CODE:
```
scores = index.search(
    query="sony headphones",
    filter="warehouse_location = 'A3-15'",
)
```

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

TITLE: Upserting Documents with Non-Searchable Metadata - TypeScript
DESCRIPTION: This snippet shows how to upsert a document including the optional `metadata` field in TypeScript. Data within `metadata` is not indexed for search but can be retrieved alongside search results, providing additional context.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

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

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

TITLE: Upserting Documents with Non-Searchable Metadata - Python
DESCRIPTION: This snippet shows how to upsert a document including the optional `metadata` field in Python. Data within `metadata` is not indexed for search but can be retrieved alongside search results, providing additional context.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

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

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

TITLE: Knowledge Base Article Document Structure Example - JavaScript
DESCRIPTION: This example demonstrates the document structure for knowledge base articles. Searchable fields like title, body, and tags are included in `content`, while administrative or reference data such as author ID, version, approver, and view count are stored in `metadata`.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

LANGUAGE: JavaScript
CODE:
```
{
  // 👇 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
  }
}
```

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

TITLE: Initializing Upstash Search Client with Configuration Object - TypeScript
DESCRIPTION: This approach allows initializing the Upstash Search client by passing a configuration object containing the `url` and `token`. This is useful for applications that need to manage connections to multiple Upstash databases, each with distinct credentials.
SOURCE: https://upstash.com/docs/search/sdks/ts/getting-started.mdx

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

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

const index = client.index("movies")
```

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

TITLE: Setting Up Next.js Project and Installing Upstash Search Package (Shell)
DESCRIPTION: This snippet provides the necessary shell commands to initialize a new Next.js application and install the `@upstash/search` package, which is the official client library for interacting with Upstash Search. These steps are prerequisites for developing a search-enabled application.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

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

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

TITLE: Retrieving Paginated Documents with Range Command in Python
DESCRIPTION: This snippet demonstrates how to use the 'range' method in the Upstash Search Python SDK to retrieve documents with pagination. It shows an initial call with an empty cursor and a subsequent call using the 'next_cursor' from the previous response to fetch the next set of documents, illustrating how to paginate through results.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/range.mdx

LANGUAGE: python
CODE:
```
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)
```

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

TITLE: Initializing Upstash Search Client with Configuration Object - Python
DESCRIPTION: This snippet illustrates how to initialize the `Search` client by passing a configuration object directly to the constructor. This method is useful for applications interacting with multiple databases or when environment variables are not preferred for credential management.
SOURCE: https://upstash.com/docs/search/sdks/py/gettingstarted.mdx

LANGUAGE: python
CODE:
```
from upstash_search import Search

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

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

TITLE: Retrieving Documents with Pagination (Basic) - TypeScript
DESCRIPTION: This snippet demonstrates a basic usage of the `range` method to retrieve documents with pagination. It sets the initial cursor to '0' and limits the number of documents per request. The response includes the next cursor and a list of documents.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/range.mdx

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

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

TITLE: Deleting Documents by IDs Array in Upstash Search (TypeScript)
DESCRIPTION: This snippet demonstrates how to delete multiple documents from an Upstash Search index by providing an array of document IDs. It shows the asynchronous call to the `delete` method and the expected response indicating the number of deleted documents.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/delete.mdx

LANGUAGE: TypeScript
CODE:
```
const response = await index.delete(["star-wars", "inception"]);
// { deleted: 2 }
```

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

TITLE: Upserting Documents with Searchable Content - Python
DESCRIPTION: This snippet demonstrates how to upsert a document using the `content` field in Python. The `content` field is required and its data is indexed, making it searchable and filterable for queries.
SOURCE: https://upstash.com/docs/search/features/content-and-metadata.mdx

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

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

TITLE: Creating and Using an Index with Upsert (TypeScript)
DESCRIPTION: This snippet illustrates how to implicitly create and use an Upstash Search index in TypeScript. Calling `index.upsert()` on a client-derived index, like 'movies', will create the index if it's new and perform the upsert operation within that index's scope. It requires an initialized Upstash Search client and uses `await` for the asynchronous operation.
SOURCE: https://upstash.com/docs/search/features/indexes.mdx

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

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

TITLE: Deleting Documents with Filter in TypeScript
DESCRIPTION: This snippet shows how to delete documents from an Upstash Search index that match a specific filter condition. The `filter` parameter takes a filter string, allowing deletion based on content fields. Note that this is an O(N) operation and can be slow for large indexes. The method returns the count of documents deleted.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/delete.mdx

LANGUAGE: typescript
CODE:
```
index.delete(filter="age > 30");
```

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

TITLE: Creating and Using an Index with Upsert (Python)
DESCRIPTION: This snippet demonstrates how to implicitly create and use an Upstash Search index in Python. When `index.upsert()` is called on a client-derived index, the specified index (`foo` in this case) is created if it doesn't exist, and subsequent operations are scoped to it. It requires an initialized Upstash Search client.
SOURCE: https://upstash.com/docs/search/features/indexes.mdx

LANGUAGE: python
CODE:
```
index = client.index("foo")
index.upsert( ... )
```

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

TITLE: Deleting Documents by ID Prefix in Upstash Search (TypeScript)
DESCRIPTION: This snippet shows how to delete multiple documents from an Upstash Search index by specifying a prefix for their IDs. All documents whose IDs start with the given prefix will be deleted, and the response indicates the total count of deleted documents.
SOURCE: https://upstash.com/docs/search/sdks/ts/commands/delete.mdx

LANGUAGE: TypeScript
CODE:
```
const response = await index.delete({
  prefix: "star-"
});
// { deleted: 3 }
```

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

TITLE: Using Equals Operator in SQL Filter Syntax
DESCRIPTION: This SQL-like filter syntax demonstrates the `equals` operator (`=`) to match content keys with specific literal values. It filters for documents where `warehouse_location` is 'A3-15' AND `in_stock` is 3. This operator is applicable to string, number, and boolean values.
SOURCE: https://upstash.com/docs/search/features/filtering.mdx

LANGUAGE: SQL
CODE:
```
warehouse_location = 'A3-15' AND in_stock = 3
```

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

TITLE: Starting the Development Server (Bash)
DESCRIPTION: This Bash command initiates the development server for the Next.js application. It allows developers to access the application locally, typically at `http://localhost:3000`, to test its functionality, including data upsertion and search queries.
SOURCE: https://upstash.com/docs/search/tutorials/nextjs.mdx

LANGUAGE: bash
CODE:
```
npm run dev
```

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

TITLE: Deleting Documents by IDs Array in TypeScript
DESCRIPTION: This snippet demonstrates how to delete multiple documents from an Upstash Search index by providing an array of their unique IDs. The `ids` parameter accepts an array of strings or numbers, specifying the exact documents to be removed. The method returns the count of successfully deleted documents.
SOURCE: https://upstash.com/docs/search/sdks/py/commands/delete.mdx

LANGUAGE: typescript
CODE:
```
index.delete(ids=["star-wars", "inception"]);
```