Filtering

How to Filter Your Data

1. Define attributes that need to be filterable (at indexing time)

Initially, filter attributes must be defined as facets, using the attributesForFaceting parameter. This is done at indexing time, using the dashboard or an API client.

If you plan on using an attribute for filtering only, and not for computing counts for each facet value, you should use the filterOnly modifier. For example, if you plan to filter on an attribute, for example color, but never need to calculate or display the number of items with color:green, color:blue, etc., then you should use filterOnly. It reduces the index size and improve the speed of the search.

Note that if you use numericFilters to filter on numeric or boolean attributes, you don’t have to set these attributes as attributesForFaceting.

2. Filter by Attributes (at query time)

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.

Filtering on objectID

By default, the engine sets a record’s objectID attribute as a filter-only facet. This means you can use the filters parameter to filter on objectID. This is useful when you want to include or exclude specific records in the current search. For example, to exclude the record with objectID “1234”, you can use the filter NOT objectID:1234 in the filters parameter of your search.

Combining Filters with Boolean Operators

Algolia’s 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

facetFilters

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 filters parameter.

optionalFilters

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.

_Tags

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, Brand and 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 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 red records.