Filtering

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 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 frontend search. This is called faceting, where filters are displayed on the search UI as clickable items, allowing users to select one or more. This enables a more refined, drilled-down search experience.

How to filter your data

The process is as follows:

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

Define filterable attributes (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, use the filterOnly modifier. For example, if you plan to filter on an attribute, such as color, but never need to calculate or display the number of items with color:green, color:blue, or similar, you should use filterOnly. It reduces the index size and improves search speed.

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

Filter by attributes (at query time)

The actual filtering of records is performed at “query time” (when searches are carried out), not “indexing time” (when your index is populated or configured). For this, use the filters parameter in your 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, more complex phrases, numbers, booleans, dates, or even arrays and nested arrays of related data. Users may use any filter combination to group records. Grouping by filters helps reduce noise, creates more targeted (relevant) subsets of data, and increases 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, and it’s useful when you want to include or exclude specific records in the current search. For example, to exclude the record with objectID “1234”, 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 use boolean operators (AND, OR, NOT) and parentheses to combine individual filters, similar to SQL expression syntax.

Alternative filter parameters and attributes

As an alternative or adjunct to the filter parameter, there are other options you can choose from:

• Facet filters
• Optional filters
• Tags

Facet filters

Instead of using the filters parameter, you can filter hits with the facetFilters parameter. They work similarly, but the filters parameter is recommended due to its more familiar SQL syntax and ability to filter on all types (strings, numbers, booleans, dates). However, there may be circumstances when you want to use facetFilters to refine the filters behavior.

Optional filters

Optional filters are mainly used for promoting content.

• When using the filters parameter, you’re telling the engine to return only those records that match the filters specified in the search.
• With the optionalFilters parameter, you’re telling the engine to return these filter-matching records and all records that match the query. Optional filtering puts filter-matching records at the top and all other query-matching records lower in the ranking order.

Tags

Algolia lets you add tags to 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.

You could use this attribute to, for example, tag books by categories or genre.

_tags is a reserved word, so it isn’t searchable by default.

How to apply filtering to the search UI

The first step in filtering is creating filter attributes and then ensuring every record is tagged appropriately. Once this is done, you’ll also want to ensure your frontend 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 called 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. While the values may change, the brand facet/refinement is always present.

Other uses for filtering

The primary use 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. However, 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 is geographically sensitive).
• Filter scoring: using filters to help promote some records over others. This is done using filter scoring to designate some filters as more important than 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 the filter value “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”, the term “dress” would search only red records.