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

// 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 conditionawait products.query({  filter: {    $should: [{ category: "electronics" }, { category: "sports" }],  },});// Optional boost: "wireless" is required, "premium" boosts score if presentawait products.query({  filter: {    $must: {      name: "wireless",    },    $should: {      description: "premium",    },  },});// Multiple optional boostersawait products.query({  filter: {    $must: {      category: "electronics",    },    $should: [      { name: "wireless" },      { description: "bluetooth" },      { description: "premium" },    ],  },});

# Match either conditionproducts.query(filter={"$should": [{"category": "electronics"}, {"category": "sports"}]})# Optional boost: "wireless" is required, "premium" boosts score if presentproducts.query(filter={"$must": {"name": "wireless"}, "$should": {"description": "premium"}})# Multiple optional boostersproducts.query(filter={    "$must": {"category": "electronics"},    "$should": [        {"name": "wireless"},        {"description": "bluetooth"},        {"description": "premium"},    ],})

# Match either conditionSEARCH.QUERY products '{"$should": [{"category": "electronics"}, {"category": "sports"}]}'# Optional boost: "wireless" is required, "premium" boosts score if presentSEARCH.QUERY products '{"$must": {"name": "wireless"}, "$should": {"description": "premium"}}'# Multiple optional boostersSEARCH.QUERY products '{"$must": {"category": "electronics"}, "$should": [{"name": "wireless"}, {"description": "bluetooth"}, {"description": "premium"}]}'