Skip to main content

​
Filter Basics

The filter_group API parameter refines results by selecting only the products that match the given expressions and running the query on those products. The filter_group expects a filter expression. 
{
  "filter_group": {
    "conditional": "AND",
    "expressions": [
      {
        "property": "product_type",
        "operator": "eq",
        "values": ["Sweater"]
      },
      {
        "property": "options.color",
        "operator": "eq",
        "values": ["RED"]
      }
    ]
  }
}

​
Expressions and Operators

Expressions are the core of the filter language. 
{
  "property": "product_type",
  "operator": "eq",
  "values": ["Sweaters"]
}
  • property is the attribute of the field you want to filter on.
  • operator is the logical operator such as in, gt, gte, lt, lte, exists, not_in, not_eq, not_exists.
  • value is the value the operator compares against in the attribute.

​
Examples of Basic Conditions

A condition to find products of type Sweaters: 
{
  "property": "product_type",
  "operator": "eq",
  "values": ["Sweaters"]
}
A condition to find products created after 1 January 2020 (UNIX Epoch time): 
{
  "property": "created_at",
  "operator": "gt",
  "values": [1577836800]
}

​
Complex Filter Expressions

You can build advanced filter groups by combining expressions using AND and OR.

​
Example of Complex Expression

To include both Accessories and products from SUPREME published after 1 January 2020: 
{
  "conditional": "OR",
  "expressions": [
    {
      "conditional": "AND",
      "expressions": [
        {
          "property": "product_type",
          "operator": "eq",
          "values": ["Accessories"]
        },
        {
          "property": "vendor",
          "operator": "eq",
          "values": ["Supreme"]
        }
      ]
    },
    {
      "conditional": "AND",
      "expressions": [
        {
          "property": "published_at",
          "operator": "gt",
          "values": ["1577836800"]
        }
      ]
    }
  ]
}

​
Best Practices for Filter Language

When crafting filter expressions:
  • Test complex expressions in a controlled environment before deployment.
  • Ensure consistent case usage for string attributes to prevent mismatches.

​
Advanced Concepts

  • Nested Expressions: Combine multiple levels of conditions.

​
Troubleshooting Filter Expressions

If your filter expression isn’t returning the expected results:
  • Check for correct operator usage.
  • Confirm that attribute names and values match exactly with the data.

​
Conclusion

The filter language is an essential tool for any developer looking to implement a nuanced and responsive search feature. With careful construction and testing of filter expressions, you can provide users with a powerful means to navigate complex datasets and inventories.