# $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
// 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
{
  $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
{
  $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
// 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
# 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
# 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>