> ## Documentation Index
> Fetch the complete documentation index at: https://docs.depict.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filters and sorts

> The filter_by syntax, the fields you can filter on, limits and errors, and the facets and sorts on `browse`.

`browse` narrows a search or a listing page with `filter_by`, a filter expression over your store's field names. This page has the whole syntax.

## Sending a filter

In a GET, percent-encode the whole value. A raw `&` ends the parameter, so `&&` must be `%26%26`, and a literal `+` must be `%2B`.

```http theme={null}
GET /v4/acme/browse?market=se&filter_by=color%3A%3D%5Bred%2Cblue%5D%20%26%26%20price%3A%5B100..500%5D
```

In a POST, send the same string as `filter_by`:

```json theme={null}
{ "market": "se", "filter_by": "color:=[red,blue] && price:[100..500]" }
```

In JavaScript, `URLSearchParams` does the encoding for you:

```js theme={null}
const params = new URLSearchParams({
  market: "se",
  filter_by: "color:=[red,blue] && price:[100..500]",
});
const res = await fetch(`https://api.depict.ai/v4/acme/browse?${params}`);
```

## Syntax

```text theme={null}
expression := and ("||" and)*
and        := primary ("&&" primary)*
primary    := "(" expression ")" | clause
clause     := field ":" ("" | "=" | "!=" | ">" | ">=" | "<" | "<=") (item | "[" item ("," item)* "]")
item       := value | number ".." number        a range: only in a list after a bare ":"
value      := bare | "`" text "`"               no backtick inside a value
```

* A bare value ends at whitespace or any of `` , ( ) [ ] & | ` ``. Put any value with spaces or those characters in backticks: `` brand:=`Acme Outdoor` ``.
* A bare value is a number, `true` or `false`, or else a string. A number is digits with an optional leading `-` and decimal part, so `1e3` is a string.
* A value in backticks is always a string. `` price:=`100` `` gets `400 invalid_filter`.
* After a bare `:`, a bare value with `..` in it is read as a range. Put it in backticks to match it as text.
* `&&` binds tighter than `||`. Use parentheses to group, up to 32 levels deep.
* An empty `filter_by` means no filter.
* Joins such as `$collection(...)`, geo filters, `!` negation and `exists` are not supported. Each gets a 400.

## Operators

| Operator | Meaning |
| - | - |
| `:=` | Exact match. `:=[a,b]` matches any of them |
| `:!=` | Matches none of them. A product without the field matches |
| `:` | Word match on strings, equality on numbers and booleans. `field:[min..max]` is a range, both ends included |
| `:>` `:>=` `:<` `:<=` | Compares with one number. A product without the field never matches |

## Fields you can filter on

When two fields share a name, the one higher in this table wins. The exception is a facet named `brand` or `category`, which replaces the built-in one.

| Field | Filters on | Kind |
| - | - | - |
| `price` | The price in the request's market | number |
| `in_stock` | Stock in the request's market | boolean |
| `brand` | The brand | string |
| `category` | Category ids | string |
| each of your facets | The facet's values | the field's type |
| each of your other filters | Its values, including filters you don't show shoppers | the field's type |
| each [merchant attribute](https://docs.depict.ai/api-v4/attributes.md) | The attribute's value | its type |
| each other product attribute in your search index | That attribute | its type |

* `price` and `in_stock` always mean the above.
* Catalogue fields such as `title`, `description`, `tags`, `product_type`, `gender`, `material` and `colors` can be filtered on only when they are one of your facets or filters.
* A field name is letters, digits, `_` and `-`, at most 128 characters. A facet on a nested attribute uses dots, as in `var_color.value`.
* Any other name gets `400 unknown_filter_field`, and `allowed` lists the names you can use.
* A new field becomes filterable a few minutes after Depict indexes it.

## Values per kind

| Kind | Operators | Values |
| - | - | - |
| number | All, and ranges in a list | Numbers only |
| boolean | `:`, `:=`, `:!=` | `true`, `false` |
| string | `:`, `:=`, `:!=` | Any |

Anything else gets `400 invalid_filter`. That covers a comparison or range on a field that isn't a number, a list after a comparison, a value of the wrong kind, and a range whose min is greater than its max.

## Limits

| Limit | Value | Over it |
| - | - | - |
| Operations | 80. Each clause counts as one, and so does each `&&` and `\|\|`. A value list counts as one at any length. Parentheses don't count. On a listing with many rules, the listing's own filters count too | `400 invalid_filter` |
| Length | 4,096 characters, in GET and POST | `400 bad_request` |
| Nesting | 32 levels of parentheses | `400 invalid_filter` |

## Errors

Every filter error is a 400 with `path: ["filter_by"]`. A syntax error names the character position.

```json theme={null}
{ "error": { "code": "invalid_filter", "message": "filter_by: expected \":\" after \"size\" at character 19",
    "request_id": "...", "path": ["filter_by"] } }
```

```json theme={null}
{ "error": { "code": "unknown_filter_field", "message": "unknown filter field \"color\"",
    "request_id": "...", "path": ["filter_by"], "allowed": ["brand", "category", "color", "in_stock", "price", "size"] } }
```

| Code | When |
| - | - |
| `invalid_filter` | The filter can't be read, is over a limit, or uses an operator or value the field's kind doesn't take |
| `unknown_filter_field` | The filter names a field you can't filter on |
| `bad_request` | The filter is over 4,096 characters |

Sometimes a field is allowed but your search index can't filter on it, such as a facet that isn't indexed. The API then drops the parts of your filter that use it and still serves the page. A dropped part is the whole `&&` term that holds the field, so a group like `(a || b)` goes as one.

## How your filter combines with Depict's

The API applies your filter together with its own conditions, as `(your filter) && (Depict's conditions)`. An `||` in your filter can't bring back a product the API leaves out. Those are inactive products, products without a price or not sold in the market, hidden products, and products outside the listing.

## Facets

Facets are the filters a shopper sees next to the results. `browse` returns them by default and with `include=facets`, in the order you set them up. A facet your search index can't count is left out, and the others are still served.

```json theme={null}
{
  "field": "color",
  "title": "Color",
  "type": "swatch",
  "expanded": true,
  "values": [
    {"value": "Black;#000000", "label": "Black", "count": 42, "selected": true, "swatch": "#000000"},
    {"value": "Yellow;#ffd400", "label": "Yellow", "count": 7, "selected": false, "swatch": "#ffd400"}
  ]
}
```

### Facet fields

| Field | Notes |
| - | - |
| `field` | The name to use in `filter_by` |
| `title` | The facet's title in the request's language |
| `type` | `checkbox`, `radio`, `swatch`, `hierarchy`, `grid` or `range` |
| `expanded` | Whether to show the facet open |
| `values` | Up to 150 values. A `range` facet has `min`, `max` and, when the filter sets one, the `selected` range instead |

Each value has the `value` to send back in a filter, a `label` to show in the request's language, a `count` and `selected`. A `swatch` value also has `swatch`, a CSS color, where you set one. Checkbox, radio and swatch values come most frequent first unless you set another order.

Values you group in your settings come back as one value. Its `value` is `g_<group name>`, its label is the group name, and its count covers every member. Send that value back to filter on the whole group.

### Built-in facets

* Price is a `range`, or a `checkbox` of prices if you set it up that way. `min` is rounded down and `max` up. They ignore the request's own price filter.
* Size is a `grid`, in size order. On listing pages its counts are products in stock in that size, and without a filter, sizes out of stock show with count 0. On search its counts are all matching products with that size, unless your store hides out-of-stock products or the filter names the size.
* Discount is a `radio` from "20% or more" to "50% or more", with values `0.2`, `0.3`, `0.4` and `0.5`. Send `discount:>=0.3` to select 30% or more. Only options with products are listed.
* Sale and stock are a `checkbox` with the one value `true`.
* A category tree is a `hierarchy`. Its labels are shown as stored.

### Counts and selection

* Counts are products, meaning cards, not variants. They cover every product that matches, not just the page.
* When the filter selects values on a facet's field alone, the facet's other values show the counts they would have without that selection. A shopper can see what each extra value adds. This holds for every facet except a `radio` facet you set up yourself, which counts with every filter applied.
* `selected` is `true` for a value your filter selects with `:=` or `:` on that field alone. On the discount facet, `:>=` or `:>` with exactly one of its four values selects that option.
* A value the shopper selected stays listed, at count 0 if needed, so the shopper can clear it. A category tree doesn't re-add such values.

### Facets that are left out

* A facet with no values is left out.
* On listing pages, so is a facet with one value and none selected. A category tree is kept.
* On search, so are a facet of only yes or no values and an unselected discount facet.

The search rules apply to any request with a `query`, including a search inside a listing.

## Sorts

Send `sort=<field>.<asc|desc>` in a GET, or `{"field", "order"}` in a POST. Both parts are required. Leave `sort` out for the default order.

| Field | Sorts by |
| - | - |
| `relevance` | On a search, how well products match the query. On a listing page, the listing's merchandising. See [Order](https://docs.depict.ai/api-v4/endpoints.md#order) |
| `price` | The price in the request's market |
| `newest` | When the product was created |
| `title` | The title, alphabetically |
| `discount` | The discount in the request's market. If your search index can't sort on it, you get the default order, not an error |
| a custom sort's field | That field |

Any other field gets `400 unknown_sort_field`, at `path: ["sort", "field"]`, and `allowed` lists your sort fields. Pins keep their slots only with the default order or `relevance`, on a listing page without a query.

The `sorts` section of a browse response lists the sorts your store offers shoppers, which can be fewer than the fields above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.