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

# $should

The `$should` operator specifies conditions where at least one should match.
Its behavior changes depending on whether it's used alone or combined with `$must`.

When `$should` is the only boolean operator in a query, it acts as a logical OR.
Documents must match at least one of the conditions to be included in results:

```ts theme={"system"}
// Match documents in electronics OR sports category
{ $should: [{ category: "electronics" }, { category: "sports" }] }
```

Documents matching more conditions score higher than those matching fewer.

When `$should` is combined with `$must`, the `$should` conditions become optional score boosters.
Documents are not required to match the `$should` conditions, but those that do receive higher relevance scores:

```ts theme={"system"}
{
  $must: { category: "electronics" },    // Required: must be electronics
  $should: { description: "premium" }    // Optional: boosts score if present
}
```

This is useful for influencing result ranking without restricting the result set.

When multiple `$should` conditions are specified, each matching condition adds to the document's score.
Documents matching more conditions rank higher:

```ts theme={"system"}
{
  $must: { category: "electronics" },
  $should: [
    { name: "wireless" },       // +score if matches
    { description: "bluetooth" }, // +score if matches
    { description: "premium" }    // +score if matches
  ]
}
```

A document matching all three `$should` conditions scores higher than one matching only one.

### Syntax Options

The `$should` operator accepts either an object or an array:

* **Object syntax**: Each key-value pair is a condition that should match
* **Array syntax**: Each element is a separate condition object that should match

Array syntax is useful when you have multiple conditions on the same field
or when building queries programmatically.

### Examples

> [tab] TypeScript
>
> ```ts theme={"system"}
> // Match either condition
> await products.query({
>   filter: {
>     $should: [{ category: "electronics" }, { category: "sports" }],
>   },
> });
>
> // Optional boost: "wireless" is required, "premium" boosts score if present
> await products.query({
>   filter: {
>     $must: {
>       name: "wireless",
>     },
>     $should: {
>       description: "premium",
>     },
>   },
> });
>
> // Multiple optional boosters
> await products.query({
>   filter: {
>     $must: {
>       category: "electronics",
>     },
>     $should: [
>       { name: "wireless" },
>       { description: "bluetooth" },
>       { description: "premium" },
>     ],
>   },
> });
> ```

> [tab] Python
>
> ```python theme={"system"}
> # Match either condition
> products.query(filter={"$should": [{"category": "electronics"}, {"category": "sports"}]})
>
> # Optional boost: "wireless" is required, "premium" boosts score if present
> products.query(filter={"$must": {"name": "wireless"}, "$should": {"description": "premium"}})
>
> # Multiple optional boosters
> products.query(filter={
>     "$must": {"category": "electronics"},
>     "$should": [
>         {"name": "wireless"},
>         {"description": "bluetooth"},
>         {"description": "premium"},
>     ],
> })
> ```

> [tab] Redis CLI
>
> ```bash theme={"system"}
> # Match either condition
> SEARCH.QUERY products '{"$should": [{"category": "electronics"}, {"category": "sports"}]}'
>
> # Optional boost: "wireless" is required, "premium" boosts score if present
> SEARCH.QUERY products '{"$must": {"name": "wireless"}, "$should": {"description": "premium"}}'
>
> # Multiple optional boosters
> SEARCH.QUERY products '{"$must": {"category": "electronics"}, "$should": [{"name": "wireless"}, {"description": "bluetooth"}, {"description": "premium"}]}'
> ```


## Related topics

- [Upsert Vectors](https://upstash.com/docs/vector/api/endpoints/upsert.md)
- [Upstash Redis with Koyeb](https://upstash.com/docs/redis/quickstarts/koyeb.md)
- [$boost](https://upstash.com/docs/redis/search/query-operators/field-operators/boost.md)
- [Redis Search Boolean Operators](https://upstash.com/docs/redis/search/query-operators/boolean-operators/overview.md)
- [Redis Queue: From FIFO Lists to a Job Queue](https://upstash.com/docs/redis/tutorials/redis_queue.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.