$should - Upstash Documentation

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:

// 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:

{
  $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:

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

TypeScript
Python
Redis CLI

// 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" },
    ],
  },
});

# 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"},
    ],
})

# 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"}]}'

​Syntax Options

​Examples

Syntax Options

Examples