Developer docs

Filters and facets

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

View as Markdown

How a filter is built#

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

KeyMatches products that
whereMeet one condition on one field
andMatch every node in the list
orMatch at least one node in the list
notDon'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#

FieldKindOperators
brand, availability, size, product_type, promotion_id, custom_label_3Texteq, in, contains, like
id, item_group_idIDeq, in
price, sale_price, quantityNumbereq, gt, lt
availability_date, expiration_dateDate and timegt, lt
OperatorValueMatches
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.

FacetArgumentsReturns
brand, availability, size, item_group_idtop_n: how many values; all when left outvalue and count, most common first
product_typelevel (default 1), split (default ">"), top_nCategories down to level deep
price, sale_pricebucket_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.