Filtering

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:

1. Define filterable attributes (at indexing time)
2. Filter by attributes (at query time)

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

First, define filter attributes as attributes for faceting. You can do this on the dashboard or with an API client.

If you only want to use an attribute for filtering, use the filterOnly modifier. 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:green, color:blue, or similar, use filterOnly.

If you use numericFilters to filter on numeric or boolean attributes, you don’t need to set these attributes as attributesForFaceting.

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, brand and 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.