Filtering Results
Apply complex and nested filters to requests using the Search or Browse APIs.
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",
"value": "Sweater"
},
{
"property": "options.color",
"operator": "eq",
"value": "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 asin
,gt
,gte
,lt
,lte
,exists
,not_in
,not_eq
,not_exists
.value
is the value theoperator
compares against in theattribute
.
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.
Was this page helpful?