Filters

tip

Both filters (map syntax) and searchFilters (array syntax) can be used in the same request. For most use cases, use the simpler filters map syntax documented in API Integration. This page documents the searchFilters array syntax for complex nested boolean logic.

For complex boolean filter scenarios, filters can be applied via the POST search endpoint using the searchFilters array.

Structure

The searchFilters array supports two types of elements:

Term filter:

{
  "filterType": "term",
  "id": "fieldName",
  "values": ["value1", "value2"]
}

Boolean filter (for nesting):

{
  "opType": "bool",
  "operator": "AND",
  "filters": [ ... ]
}

Property	Description
id	Field name to filter on
filterType	term, range, slider, tree, humandate, relativerange, dateRangeInPeriod
values	Array of filter values
opType	Set to bool for boolean combinations
operator	AND, OR, NOT
filters	Nested array of filters (for boolean combinations)

Examples

Filter for men's shoes in colors black or blue:

Filter: color:(black OR blue) AND gender:male

{
  "q": "shoes",
  "searchFilters": [
    {
      "filterType": "term",
      "id": "color",
      "values": ["black", "blue"]
    },
    {
      "filterType": "term",
      "id": "gender",
      "values": ["male"]
    }
  ]
}

Filter for men's shoes in black/blue OR shoes on sale:

Filter: (color:(black OR blue) AND gender:male) OR sale:true

{
  "q": "shoes",
  "searchFilters": [
    {
      "opType": "bool",
      "operator": "OR",
      "filters": [
        {
          "opType": "bool",
          "operator": "AND",
          "filters": [
            {
              "filterType": "term",
              "id": "color",
              "values": ["black", "blue"]
            },
            {
              "filterType": "term",
              "id": "gender",
              "values": ["male"]
            }
          ]
        },
        {
          "filterType": "term",
          "id": "sale",
          "values": ["true"]
        }
      ]
    }
  ]
}

Filter for men's shoes in black/blue OR shoes on sale, excluding out of stock:

Filter: ((color:(black OR blue) AND gender:male) OR sale:true) AND NOT stock:0

{
  "q": "shoes",
  "searchFilters": [
    {
      "opType": "bool",
      "operator": "OR",
      "filters": [
        {
          "opType": "bool",
          "operator": "AND",
          "filters": [
            {
              "filterType": "term",
              "id": "color",
              "values": ["black", "blue"]
            },
            {
              "filterType": "term",
              "id": "gender",
              "values": ["male"]
            }
          ]
        },
        {
          "filterType": "term",
          "id": "sale",
          "values": ["true"]
        }
      ]
    },
    {
      "opType": "bool",
      "operator": "NOT",
      "filters": [
        {
          "filterType": "term",
          "id": "stock",
          "values": ["0"]
        }
      ]
    }
  ]
}