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

# Overview

Boolean operators combine multiple conditions to build complex queries.
They control how individual field conditions are logically combined to determine which documents match.

### Available Operators

| Operator                 | Description                                                                                |
| ------------------------ | ------------------------------------------------------------------------------------------ |
| [`$must`](./must)        | All conditions must match                                                                  |
| [`$should`](./should)    | At least one condition should match, or acts as a score booster when combined with `$must` |
| [`$mustNot`](./must-not) | Excludes documents matching any condition                                                  |
| [`$boost`](./boost)      | Adjusts the score contribution of a boolean clause                                         |

### How Boolean Operators Work Together

Boolean operators can be combined in a single query to express complex logic.
The operators work together as follows:

1. **`$must`** defines the required conditions. Documents must match ALL of these.
2. **`$should`** adds optional conditions:
   * When used alone: documents must match at least one condition
   * When combined with `$must`: conditions become optional score boosters
3. **`$mustNot`** filters out unwanted documents from the result set.

### Combining Operators

Here's an example that uses all three operators together:

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    // Find in-stock electronics, preferring wireless products, excluding budget items
    await products.query({
      filter: {
        $must: {
          category: "electronics",
          inStock: true,
        },
        $should: [
          { name: "wireless" },
          { description: "bluetooth" },
        ],
        $mustNot: {
          description: "budget",
        },
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Find in-stock electronics, preferring wireless products, excluding budget items
    products.query(filter={
        "$must": {"category": "electronics", "inStock": True},
        "$should": [{"name": "wireless"}, {"description": "bluetooth"}],
        "$mustNot": {"description": "budget"},
    })
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    # Find in-stock electronics, preferring wireless products, excluding budget items
    SEARCH.QUERY products '{"$must": {"category": "electronics", "inStock": true}, "$should": [{"name": "wireless"}, {"description": "bluetooth"}], "$mustNot": {"description": "budget"}}'
    ```
  </Tab>
</Tabs>

This query:

1. **Requires** documents to be in the "electronics" category AND in stock
2. **Boosts** documents that mention "wireless" or "bluetooth" (but doesn't require them)
3. **Excludes** any documents containing "budget" in the description

### Nesting Boolean Operators

Boolean operators can be nested to create more complex logic:

<Tabs>
  <Tab title="TypeScript">
    ```ts theme={"system"}
    // Find products that are either (premium electronics) OR (discounted sports items)
    await products.query({
      filter: {
        $should: [
          {
            $must: {
              category: "electronics",
              description: "premium",
            },
          },
          {
            $must: {
              category: "sports",
              price: { $lt: 50 },
            },
          },
        ],
      },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={"system"}
    # Find products that are either (premium electronics) OR (discounted sports items)
    products.query(filter={
        "$should": [
            {"$must": {"category": "electronics", "description": "premium"}},
            {"$must": {"category": "sports", "price": {"$lt": 50}}},
        ],
    })
    ```
  </Tab>

  <Tab title="Redis CLI">
    ```bash theme={"system"}
    # Find products that are either (premium electronics) OR (discounted sports items)
    SEARCH.QUERY products '{"$should": [{"$must": {"category": "electronics", "description": "premium"}}, {"$must": {"category": "sports", "price": {"$lt": 50}}}]}'
    ```
  </Tab>
</Tabs>