# Filters and facets

> Leave products out with filter_term, and count the options for a filter sidebar with facets.

## How a filter is built

`filter_term` takes a small tree. Each node has exactly one key:

| Key | Matches products that |
|-----|-----------------------|
| `where` | Meet one condition on one field |
| `and` | Match every node in the list |
| `or` | Match at least one node in the list |
| `not` | Don't match the node |

A condition names the field under `record`, then an operator, then the value:

```graphql
{ where: { record: { brand: { eq: { value: "Nike" } } } } }
```

Nodes nest, so `and`, `or` and `not` can hold each other:

```graphql
{
  and: [
    { where: { record: { availability: { eq: { value: "in_stock" } } } } }
    {
      or: [
        { where: { record: { brand: { eq: { value: "Nike" } } } } }
        { where: { record: { brand: { eq: { value: "Reebok" } } } } }
      ]
    }
    { not: { where: { record: { brand: { eq: { value: "Crocs" } } } } } }
  ]
}
```

## Fields and operators

| Field | Kind | Operators |
|-------|------|-----------|
| `brand`, `availability`, `size`, `product_type`, `promotion_id`, `custom_label_3` | Text | `eq`, `in`, `contains`, `like` |
| `id`, `item_group_id` | ID | `eq`, `in` |
| `price`, `sale_price`, `quantity` | Number | `eq`, `gt`, `lt` |
| `availability_date`, `expiration_date` | Date and time | `gt`, `lt` |

| Operator | Value | Matches |
|----------|-------|---------|
| `eq` | `{ value: "..." }` | Exactly this value |
| `in` | `{ values: ["...", "..."] }` | Any of these values |
| `contains` | `{ values: ["..."] }` | A list field, such as `promotion_id`, that holds these values |
| `like` | `{ value: "Home > Women%" }` | A pattern, where `%` stands for any run of characters |
| `gt`, `lt` | `{ value: 50 }` | Strictly greater or less than the value |

`gt` and `lt` on the same field make a range. For "at least" or "at most", wrap the opposite condition in `not`:

```graphql
{ where: { record: { price: { gt: { value: 20 }, lt: { value: 80 } } } } }
```

```graphql
{ not: { where: { record: { price: { lt: { value: 80 } } } } } }
```

Dates are ISO 8601 date-times:

```graphql
{ where: { record: { expiration_date: { gt: { value: "2026-12-31T00:00:00Z" } } } } }
```

## Common filters

**A category and everything under it.** `product_type` is a path such as `Home > Women > Shoes`, so match its start:

```graphql
{ where: { record: { product_type: { like: { value: "Home > Women%" } } } } }
```

**Several brands:**

```graphql
{ where: { record: { brand: { in: { values: ["adidas", "Nike", "Diesel"] } } } } }
```

**In stock.** Solenya keeps `availability` as your feed spells it, and feeds use either `in_stock` or `in stock`. Match yours, or both:

```graphql
{ where: { record: { availability: { in: { values: ["in_stock", "in stock"] } } } } }
```

**On a promotion.** `promotion_id` is a list, so use `contains`:

```graphql
{ where: { record: { promotion_id: { contains: { values: ["40944"] } } } } }
```

**Under a price.** `sale_price` is only set on items with a sale price, so a `sale_price` condition leaves out everything at full price.

```graphql
{ where: { record: { price: { lt: { value: 800 } } } } }
```

## Facets

Facets count the products behind each filter option, for a sidebar like "Nike (124)". They count every product that matches `filter_term`, not just the current page. The search text, product or image in `rank_with` doesn't narrow them; only `filter_term` and `distinct_on` do.

| Facet | Arguments | Returns |
|-------|-----------|---------|
| `brand`, `availability`, `size`, `item_group_id` | `top_n`: how many values; all when left out | `value` and `count`, most common first |
| `product_type` | `level` (default 1), `split` (default `">"`), `top_n` | Categories down to `level` deep |
| `price`, `sale_price` | `bucket_size` (default 10) | `range` and `count` per price band |

`level` cuts the category path. For `Home > Men > Shoes`, level 1 gives `Home`, level 2 gives `Home > Men` and level 3 gives the full path.

Ask for facets on their own, for example to build a sidebar before any search:

```graphql
query SidebarCounts {
  items {
    merchant_feed(
      filter_term: { where: { record: { availability: { eq: { value: "in_stock" } } } } }
      distinct_on: { selector: item_group_id }
    ) {
      facets {
        brand(top_n: 20) {
          value
          count
        }
        product_type(level: 2) {
          value
          count
        }
        price(bucket_size: 100) {
          range
          count
        }
      }
    }
  }
}
```

To get facets and results in one request, ask for `facets` and `page` side by side, as in [A full search page](https://solenya.ai/docs/search.md#a-full-search-page). `page_info.facets` gives the same counts for the products on one page only.
