Skip to main content
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

OperatorDescription
$mustAll conditions must match
$shouldAt least one condition should match, or acts as a score booster when combined with $must
$mustNotExcludes documents matching any condition
$boostAdjusts 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: 
// 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",
    },
  },
});
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: 
// 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 },
        },
      },
    ],
  },
});