Skip to main content

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.

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

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