# Filtering

Source: https://developers.swell.is/backend-api/querying/filtering

Use the `where` parameter to filter results by field values. Swell offers native support for many [MongoDB Query Operators](https://www.mongodb.com/docs/v4.4/reference/operator/query/), 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.

| Name | Description |
| --- | --- |
| $eq | Matches values that are equal to a specified value. |
| $ne | Matches values that are not equal to a specified value. |
| $gt | Matches values that are greater than a specified value. |
| $gte | Matches values that are greater than or equal to a specified value. |
| $lt | Matches values that are less than a specified value. |
| $lte | Matches values that are less than or equal to a specified value. |
| $in | Matches any of the values specified in an array. |
| $nin | Matches none of the values specified in an array. |
| $regex | Selects records where values match a specified regular expression. |
| $type | Matches records if a field is of a specified type. |
| $exists | Matches records that have a specified field defined. |

**Comparison and evaluation operator examples**

**Node**

```javascript
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.

| Name | Description |
| --- | --- |
| $and | Joins query clauses with a logical AND operation. |
| $or | Joins query clauses with a logical OR operation. |
| $nor | Joins query clauses with a logical NOR returns all records that fail to match both clauses. |
| $not | Inverts the effect of an operator expression on a single field. |

**Logical operator examples**

**Node**

```javascript
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.

| Name | Description |
| --- | --- |
| $all | Matches arrays that contain all elements specified in the query. |
| $elemMatch | Selects records if element in the array field matches all the specified $elemMatch conditions. |
| $size | Selects records if the array field is a specified size. |

**Array operator examples**

**Node**

```javascript
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 }
	}
});
```

## Example request

**Example query using where**