On this page
Filtering allows your users to drill-down and create a smaller, more manageable set of data based on meaningful categories. 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 many other kinds of information that help classify your data. By classifying your data with filtering, you give your users direct control over the set of records they query.
Filtering is primarily used in the context of front-end search. We call this faceting, where filters are displayed on the search UI as clickable items, allowing users to select one or more filters. This enables a more refined, drilled-down search experience.
How to Filter Your Data
1. Define attributes that need to be filterable (at indexing time)
Initially, all filter attributes must be defined as facets - attributesForFaceting. This is done at indexing time using the Dashboard or an API client.
2. Filter by Attributes (at query time)
Once that’s done, the actual filtering of records is performed at query time, not at indexing time. For this, you need to use the filters parameter in your search code.
In all cases, filtering is based on attributes. Every record has one or more attributes that are designated as filters. A filter attribute can be a list of single words, or more complex phrases, or numerics, booleans, dates, or even arrays and nested arrays of related data. In the end, every filter or combination of filters can be used to group two or more records together. Ultimately, grouping by filters helps reduce noise, creating more targeted (relevant) subsets of data and increasing the chance that only the best results appear at the top.
Combining Filters with Boolean Operators
filters parameter allows you to leverage boolean operators (AND, OR, NOT) and parentheses to combine individual filters, similar to SQL expression syntax.
Alternative Filtering Methods
It’s possible to filter hits using the facetFilters parameter. The functionality is mostly the same - they both filter records based on certain attributes. However, because of its more familiar SQL syntax and its ability to filter on all types (strings, numbers, booleans, dates), we suggest using the
When using filters, you are telling the engine to return only those records that match the filter(s) specified in the search. With optionalFilters, you are telling the engine to return not only filter-matching records, but all records that match the query. The difference is that optional filtering puts filter-matching records at the top and all other query-matching records lower in the ranking order. Optional filters are mainly used for [promoting] (/doc/guides/managing-results/refine-results/merchandising-and-promoting/).
Algolia lets you add tags to each of your records thanks to the special attribute _tags. This reserved Algolia attribute automatically works as a filter without you having to set it as an attribute for faceting.
Therefore, we can leverage this attribute and tag books by categories or genre.
Note: _tags is a reserved word and so it is not searchable by default.
How to apply filtering to the Search UI
The first step in filtering is to create filter attributes, and then to make sure every record is tagged appropriately. Once this is done, you’ll also want to make sure that your frontend UI accurately represents all filtering possibilities. You do this with facets (called Refinements in InstantSearch).
You’ll typically want to display all filtering categories (facets/refinements). Thus, if you have created two filters,
Price Range, you’ll always want to see a list of brands and a price range slider for every query. The effect is that while the actual category values may change, the categories themselves will always be present. This is what we call static faceting. For example, a search for phones will return brands like Apple and Samsung, while a search for stereos will return Panasonic and Bose. So while the values may change, the
brand facet/refinement is always present.
Alternative benefits of filtering
Other Use Cases
The main use case for filtering is to enable users to refine their search with string categories or numeric ranges, and so on, thereby limiting the range of data that they search within.
There are other use cases for filters.
- Security-filtering: You can use filters as a security measure, where each user has access to only their own private data.
- Geo-filtering: You can filter on the geo location of the user, if your index is geographically sensitive.
- Filter Scoring: You can use filters for merchandising, to help promote some records over others. This is done by using filter scoring, where you can designate some filters as more important than others.
- Query-Based Filtering: You can set up rules (Query Rules) that parse your users’ queries and use certain query terms as filters instead of search terms. For example, if a user types in a filter value - say, “red” - that term can be used as a filter instead of as a search term, thereby returning all red records. If the full query had been “red dress”, then the term “dress” would search only