On this page
Filtering allows your users to drill down and create a smaller, more manageable set of results based on meaningful categories. It gives them direct control over the records they query. Categories can be brand, color, or genre of film. They can be dress or shoe sizes or price ranges like expensive or cheap. They can be date ranges, booleans, user-defined tags, geolocation, and other information that helps classify your data.
The most common use for filtering is to provide a UI that enables users to refine their search using one or more clickable items.
How to filter your data
The process is as follows:
Most records have one or more attributes, such as color, brand, genre, or category, that you can choose as a filter. A filter attribute can be a list of single words, more complex phrases, numbers, booleans, dates, or even arrays and nested arrays of related data. Users may use any filter combination to group records. Filtering creates more targeted and therefore relevant subsets of results, and increases the chance that only the best results appear at the top.
Define filterable attributes
If you only want to use an attribute for filtering, use the
This reduces the index size and improves search speed.
For example, if you plan to filter on an attribute, such as
color, but don’t need to calculate or display the number of items with
color:blue, or similar, use
If you use
numericFilters to filter on numeric or boolean attributes, you don’t need to set these attributes as
Filter by attributes
The actual filtering of records happens at “query time” (when the user searches), not “indexing time” (when your index is populated or configured).
How to apply filtering to the search UI
After defining filterable attributes and ensuring users can filter every record with the appropriate attributes, ensure your frontend represents all these possibilities by using InstantSearch’s refinements.
You’ll typically want to display all filtering categories. Thus, if you have created two filters,
price_range, you’ll always want to display a list of brands and a price range slider for every query in your UI.
For example, a search for “phones” returns brands like Apple and Samsung, while a search for “speakers” returns Panasonic and Bose.
While the values may change, the
brand filter is always present.
Other uses for filtering
Although the most common use for filtering is to enable users to refine their search and limit the records they search within, there are other ways to use filters. For example:
- Security-filtering: using filters as a security measure, where each user has access to only their private data.
- Geo-filtering: filtering on the user’s geolocation (if your index has geographical data).
- Filter scoring: using filters to help promote some records over others.
- Query-based filtering: setting rules that parse your users’ queries and use specific query terms as filters instead of search terms. For example, if a user types in “red”, “red” can be used as a filter instead of a search term, thereby returning all red records.