Developer docs
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:
{ where: { record: { brand: { eq: { value: "Nike" } } } } }Nodes nest, so and, or and not can hold each other:
{
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:
{ where: { record: { price: { gt: { value: 20 }, lt: { value: 80 } } } } }{ not: { where: { record: { price: { lt: { value: 80 } } } } } }Dates are ISO 8601 date-times:
{ 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:
{ where: { record: { product_type: { like: { value: "Home > Women%" } } } } }Several brands:
{ 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:
{ where: { record: { availability: { in: { values: ["in_stock", "in stock"] } } } } }On a promotion. promotion_id is a list, so use contains:
{ 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.
{ 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:
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. page_info.facets gives the same counts for the products on one page only.