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

# Content and Metadata

> How to use content and metadata fields in your documents

**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.

***

## Content

The `content` field contains the searchable data of your documents. This is what gets indexed and can be queried.

* **Required**: You must provide `content` when upserting documents
* **Format**: JSON object structure
* **Searchable**: All fields within content are indexed for search
* **Filterable**: Content fields can be used in filter queries

<Tabs>
  <Tab title="Python">
    ```py theme={"system"}
    index.upsert(
      documents=[
        {
          "id": "star-wars",
          "content": { "text": "Star Wars is a sci-fi space opera."}
        }
      ]
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    await index.upsert([
      {
        id: "star-wars",
        content: { title: "Star Wars", genre: "sci-fi", category: "classic" }
      }
    ]);
    ```
  </Tab>
</Tabs>

***

## Metadata

The `metadata` field stores additional context about your documents that won't be indexed for search. This is useful for data you want to retrieve with your search results but don't need to search through.

* **Optional**: You can upsert documents without metadata
* **Format**: JSON object structure
* **Not Searchable**: Metadata fields are not indexed

<Tabs>
  <Tab title="Python">
    ```py theme={"system"}
    index.upsert(
      documents=[
        {
          "id": "star-wars",
          "content": { "text": "Star Wars is a sci-fi space opera."},
          "metadata": {
            "genre": "sci-fi",
          }
        }
      ]
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"system"}
    await index.upsert([
      {
        id: "star-wars",
        content: { title: "Star Wars", genre: "sci-fi", category: "classic" },
        metadata: { director: "George Lucas" } ,
      }
    ]);
    ```
  </Tab>
</Tabs>

***

## Best Practices

| Use Content When                                      | Use Metadata When                                    |
| ----------------------------------------------------- | ---------------------------------------------------- |
| Users need to search for this information             | Information is for display/reference only (e.g. IDs) |
| The field is important for finding relevant documents | The field provides context after finding documents   |
| You want to filter results by this field              | You need to track internal system information        |

***

## Examples & Common Patterns

1. E-commerce Products

```javascript theme={"system"}
{
  // 👇 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"
  }
}
```

2. Knowledge Base Articles

```javascript theme={"system"}
{
  // 👇 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
  }
}
```

3. News Articles

```javascript theme={"system"}
{
  // 👇 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
  }
}
```