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

<Tabs>
  <Tab title="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>

  <Tab title="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>

  <Tab title="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"}]}'
    ```
  </Tab>
</Tabs>