Today, we are releasing Query Rules, a new feature which enables you to modify, override, & enhance the behavior of the engine’s configured ranking for a subset of the queries. We wanted to share with you how we approached this key addition to our API, why we decided to build it, and explain the design steps leading to the release today.

Before we dive in, let’s look at a few examples of what you can do with Query Rules:

• Transform descriptive text into a filter: for example, by automatically transforming a query word into its equivalent filter (“cheap” would become a filter price< 400; “red” a filter on the color…)
• Merchandising: manually select a result for a specific query (e.g., decide that the latest iPhone 8 should be in the first position for the query iPhone)
• Entities detection: detect entities (colors, brands…) in the queries and transform them into filters or boosts

Building upon our ranking formula

With Algolia, the same relevance algorithm is applied across the entire index. We expose features like Custom Ranking so that customers can customize the ranking strategy for their needs, and achieve a great relevance for the vast majority of queries. However, in the past few years, our customers started to bring to us examples of outlier queries.

We began compiling a list of these outlier situations. Here are a few examples:

• When Apple releases a new iPhone, it should be in the first position of the list for the query “iPhone” (even though at this stage it has no views, no sales… no “logical” reason to be ranked high)
• You need to get rid of a big stock of a specific model of a vacuum cleaner, so you’d like it to be promoted in the results (at least until enough units are sold)
• The query “phone” naturally (according to the configured ranking strategy) retrieves feature phones instead of smartphones, but you’d like to highlight smartphones first
• The query “red dress” matches with non-red results because the name of the brand begins by “red”
• The query “cheap phone” doesn’t return any results (the records don’t contain the word cheap), and would behave better if “cheap” was transformed into a numeric filter on the price
• Queries originating from users on mobile devices should highlight results that are mobile-friendly

There are hundreds of examples like this where having an exception to the general rule would make sense, either to improve the relevance, or to override the ranking for business reasons.

Thinking about our options

There are two main ways to address the types of exceptions we were seeing. The natural way to handle this would be to analyze the use cases one by one and add a configuration to the engine to handle each of them individually. We could, for example, develop a form of synonyms that would transform a word into a filter. Eventually, these settings would form a merchandising tool, allowing users to tweak and override the ranking logic.

We certainly had the experience on the team to execute on this approach. Several team members, including our founders, have used, or even built merchandising platforms prior to founding/working for Algolia. However, it is exactly because of this experience that we had doubts that this was the right approach:

• Creating a new setting inside the engine for each exception quickly leads to a bloated solution: there are just too many varieties of merchandising strategies
• Building a quality merchandising tool that would work for all of our users – each of whom have specific needs & exceptions – is virtually impossible
• Multiplying the exceptions inevitably affects performance

More importantly, we wanted to do more than merchandising and address the needs of other industries. Media sites don’t use merchandising, but they still want to promote, for example, partner content. SaaS systems may want to improve the ranking by adding rules automatically based on the output of a machine learning tool.

To do this, we would need to be able to impact search results on a subset of queries in two distinct places:

• Before the search query is processed, in order to override the query parameters
• After the results are found, in order to modify the results list

The solution

What we came up with is a rules system for queries — or Query Rules — that sits inside the engine via two modules:

• A query preprocessing module that will modify the search parameters before the search is processed by the engine
• A results postprocessing module that will modify the results before they are sent back to our users

Each rule has the following pattern: IF the query contains X, THEN modify Y. A condition and a consequence:

• If the query contains “iPhone”, add this result in the first position
• If the query is “cheap phone”, replace the word “cheap” by a numeric filter price<200
• If the query contains a color, filter by that color

This approach makes it simple to modify the behavior of a subset of the queries, without impacting the rest of the queries. We created two types of conditions, and seven types of consequences, which together allow us to handle a variety of exceptions, including:

• Promote the latest iPhone on the query “iphone”
• Filter on color white for the query “white dress”
• Filter on price<400 for the query “cheap phone”
• Display a promotional banner for the query Samsung
• Remove the word “hotel” in a hotels search

Conclusion

With Query Rules, we’re bringing to Algolia the ability to handle queries on an individual basis by making exceptions on the regular ranking strategy.

We think the approach we took has a few interesting benefits:

• It is low-level and flexible enough to adapt to a large variety of use-cases without requiring a lot of settings and configuration
• It is exposed via an API, allowing both our customers and potential partners specialized on merchandising to build upon it
• It doesn’t compromise performance for the sake of feature sets: you can add up to a million rules to an index, with little to no impact on search performance

In fact, we like to think of Query Rules as more than a feature: we like to think of it as an extension of our engine. We have designed it to be open-ended enough to allow our users to solve their own unique problems and push the boundaries of what is possible with search.

It’s been exciting to start sharing the feature with a few beta testers — we’ve been amazed at how easily they grasped its potential, and the combinations it allows.

The two conditions and seven consequences we are initially releasing are only the beginning — we look forward to getting your feedback and learning which ones you’d like us to add next!

Meanwhile, we put together an online workshop, where two of our team members will show you in practice how to create smarter search with Query Rules.
=> You can register here.