Use the where parameter to filter results by field values. Swell offers native support for many MongoDB Query Operators, and you can combine multiple fields and operators together.

Top-level query parameters that aren't reserved are treated as filters automatically—?active=true is equivalent to where[active]=true.

Comparison and evaluation operators

These operators are used to filter results based on the values of certain fields, with matching based on existence, data type, regex evaluation, equality, and greater/less than comparisons.

NameDescription
$eqMatches values that are equal to a specified value.
$neMatches values that are not equal to a specified value.
$gtMatches values that are greater than a specified value.
$gteMatches values that are greater than or equal to a specified value.
$ltMatches values that are less than a specified value.
$lteMatches values that are less than or equal to a specified value.
$inMatches any of the values specified in an array.
$ninMatches none of the values specified in an array.
$regexSelects records where values match a specified regular expression.
$typeMatches records if a field is of a specified type.
$existsMatches records that have a specified field defined.
Comparison and evaluation operator examples
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

// Find products on sale
await swell.get('/products', {
  where: { 
    sale: true
  }
});

// Find products with price above $10
await swell.get('/products', {
  where: { 
    price: { $gt: 10 }
  }
});

// Find products with price of $10 or above
await swell.get('/products', {
  where: { 
    price: { $gte: 10 }
  }
});

// Find products with price below $50
await swell.get('/products', {
  where: { 
    price: { $lt: 50 }
  }
});

// Find products with price of $50 or less
await swell.get('/products', {
  where: { 
    price: { $lte: 50 }
  }
});

// Find products with price between $10 and $50
await swell.get('/products', {
  where: { 
    price: { $gte: 10, $lte: 20 }
  }
});

// Find products with a material attribute of 'Silver', 'Gold', or 'Titanium'
await swell.get('/products', {
  where: { 
    'attributes.material': { $in: ['Silver', 'Gold', 'Titanium'] }
  }
});

// Find products without a material attribute of 'Polyester' or 'Nylon'
await swell.get('/products', {
  where: { 
    'attributes.material': { $nin: ['Polyester', 'Nylon'] }
  }
});

// Find products that contain the word 'chair' in the name, ignoring case
await swell.get('/products', {
  where: {
    name: { $regex: 'chair', $options: 'i' }
  }
});

// Find products with a subscription purchase option
await swell.get('/products', {
  where: {
    'purchase_options.subscription': { $exists: true }
  }
});

// Find products with a SKU string defined
await swell.get('/products', {
  where: {
    sku: { $type: 'string' }
  }
});

Logical operators

Logical operators are used to define multiple conditions in a query with logical evaluations. By default, Swell parses multiple attributes in a where object with the $and operator, so you don’t need to explicitly use this unless your query also requires another type of logical operator.

NameDescription
$andJoins query clauses with a logical AND operation.
$orJoins query clauses with a logical OR operation.
$norJoins query clauses with a logical NOR returns all records that fail to match both clauses.
$notInverts the effect of an operator expression on a single field.
Logical operator examples
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

// Find orders created between July 1st, 2022 and June 30th, 2023
await swell.get('/orders', {
  where: {
    $and: [
      { date_created: { $gt: '2022-07-01T00:00:00Z' }},
      { date_created: { $lt: '2023-06-30T00:00:00Z' }}
    ]
  }
});

// This shorthand syntax also works
await swell.get('/orders', {
  where: {
    date_created: { $gt: '2022-07-01T00:00:00Z', $lt: '2023-06-30T00:00:00Z' }
  }
});

// Find active products with a stock level below 10
await swell.get('/products', {
  where: {
    $and: [
      { stock_level: { $lt: 10 }},
      { active: true},
    ]
  },
});

// This shorthand syntax also works
await swell.get('/products', {
  where: {
    stock_level: { $lt: 10 },
    active: true,
  },
});

// Find products with a material attribute of 'Silver' and a price under $100.
await swell.get('/products', {
  where: {
    $and: [
      { 'attributes.material': 'Silver' },
      { price: { $lt: 100 }}
    ] 
  }
});

// Find products that are on sale or have a price under $50.
await swell.get('/products', {
  where: {
    $or: [
      { sale: true }, 
      { price: { $lt: 50 }}
    ]
  }
});

// Find orders which are not delivered, not paid, and not cancelled
await swell.get('/orders', {
  where: {
    $nor: [
      { delivered: true },
      { paid: true },
      { status: 'cancelled' }
    ]
  }
});

Array operators

Array operators are used to query and update records based on items in an array field.

NameDescription
$allMatches arrays that contain all elements specified in the query.
$elemMatchSelects records if element in the array field matches all the specified $elemMatch conditions.
$sizeSelects records if the array field is a specified size.
Array operator examples
const { swell } = require('swell-node');
swell.init('store-id', 'secret-key');

// Find products with the tags "consumable" and "organic"
await swell.get('/products', {
  where: {
    tags: { $all: ['consumable', 'organic'] }
  }
});

// Find orders that have a specific coupon applied
await swell.get('/orders', {
  where: {
    discounts: {
      $elemMatch: {
        source_id: '634701a8d394db00135df1bc'
      }
    }
  }
});

// Find orders that have a specific promotion applied
await swell.get('/orders', {
  where: {
    discounts: {
      $elemMatch: {
        type: 'promo-62bc63e193cb7c0019423b6e'
      }
    }
  }
});

// Find orders that include two particular products
await swell.get('/orders', {
  where: {
    items: {
      $all: [
        { $elemMatch: { product_id: '628ba6011869c10019b41f70' }},
        { $elemMatch: { product_id: '628ba442499bba0019b1a96d' }}
      ]
    }
  }
});

// Find orders that include either of two particular products as a subscription
await swell.get('/orders', {
  where: {
    items: {
      $elemMatch: {
        product_id: {
          $in: [ '62b1e30767145000197b2bbf', '62b1dfc4d9dce40019a65797' ]
        },
        'purchase_option.type': 'subscription'
      }
    }
  }
});

// Find orders that only have one item
await swell.get('/orders', {
  where: {
    items: { $size: 1 }
  }
});