Icon query rules white

Query Rules Overview

Last updated 14 September 2017

What is Query Rules?

Query Rules allows you to target specific search terms and alter the way the Algolia engine would normally treat those terms. The benefit is clear: you can single-out a specific set of circumstances that needs special attention, while not impacting any search that falls outside of that context. Query rules illustration

We provide here both a history and a number of examples to illustrate what Query Rules can do. After that, we go into technical detail to get you started coding.

What is Query Rules solving?

As part of customer support, we take note of frequent requests, looking for patterns. When a pattern persists, we take a step back and think about how we can best address the problem.

Our new Query Rules API comes directly out of this process, as it addresses a number of recurring and similarly-related customer requests.

For example, we’ve had many requests for word detection - Do we have a mechanism that could weigh words differently depending on context, thereby creating more semantic relevance? Can the Algolia engine dynamically adapt its behavior to what a user types?

Up to now, if a customer wanted this kind of targeted, dynamic behavior, we advised changing settings, defining different data attributes, and using features such as synonyms, query expansion, and personalization. In other words, we relied on existing functionality that, when put together, more or less achieved the desired results. But these solutions required some extra implementation work, and they also applied to every search, thereby improving the relevance for some queries but degrading it for others.

Consider “red t-shirt”. If a customer wanted Algolia to recognize “red” as a color and therefore search only in the color attribute whenever “red” was typed in, or to show only “shirts” whenever the engine detected a kind of shirt like “t-shirt”, we would need a new mechanism for this.

Query Rules has been built for this.

When to use Query Rules?

While going through the below examples, keep in mind that Query Rules changes one or both of the following:

  • the query, by changing the content of the results (pre-processing)
  • the relevance, by reordering the results (post-processing)

You can think of Query Rules as an If This Then That logic: If Apple is the query, then put iPhone at the top.

Query rules schema

We expect that you will not need to use Query Rules in ninety-nine percent of your use-cases. With Custom Ranking and a well-configured index (here, here, here, …) — tweaked with our API interface — the Algolia engine should normally produce the kind of results you want. But there are some situations that will fall through the cracks.

Hit Promotion

Merchandising is about altering the textual relevance of a query: I want Record X to appear first in the results for a specific query. Without Query Rules, you can still promote Record X, but it will impact all queries. With Query Rules, you can apply the boost to a specific query or a specific pattern of query without altering the rest of the results or any other searches.

An easily understood example of boosting is where a book store wants to recommend a Harry Potter Box Set whenever the words Harry Potter form part of a search.

Another concrete example of boosting is how to manage new releases of one of your best-selling widgets - say, the newest phone. You’ve placed “best-selling items” at the top of your search results by using Custom Ranking. But the newest release - Where does that go? Nobody’s bought it yet, and so it won’t get to the top. Actually, it’s probably on the last page. So how do you promote new releases?

One solution is to create a new release boost attribute that ensures new releases to appear at the top, as described in this tutorial. But this adds volume, and is not as precise as Query Rules.

You can simplify this by using the Query Rules Hit Promotion feature, which allows you to set up a rule telling the engine that whenever Phone Brand X is searched for, place its newest Version 10 at the top, but for the rest of the same brand phones, continue sorting by most-sold.

Market Segmentation

We can go further with this and add market segmentation - age groups, for example. If you want to promote hits differently depending on age, Query Rules enables you to extend the above logic to age-range faceting (for more Query Rules and Facets, see below). So with the following age brackets:

  • “12-25 yo”
  • “26-40 yo”
  • “41-65 yo”

You can then promote different hits and display unique banners for each age group.

In the same spirit, query rules can replace the word “cheap” with the condition “price < a certain low amount”. See below for an example of this.

Alter the query by removing words or recognizing keywords

A good example of altering a query is with an online document library that allows keyword searches inside documents. If a user types in the word “article ref21”, they are probably signalling to the system that they are looking for an article whose title or id contains “ref21”. Article, in this context, is a keyword; ref21 is an id.

Currently, Algolia wouldn’t return the expected results because:

  • the engine would search using both the word “article” and the word “ref21”
  • but unfortunately, the document records don’t contain the word “article”.

Query Rules can fix this: when we see the pattern “article ref”, we remove “article” to change the query to look in the id field for the typed-in “ref” id. By doing that, “article ref21” would be replaced by “ref21”, and we would therefore only find records containing “ref21”.

There are of course workarounds, but they would not be simple. Query Rules is designed for this, to easily create rules that recognize keywords like “article” or “financial report” and remove them from the search, focusing the search exclusively on the article’s title or reference id.

Dynamic Facets & Filters

Imagine a query “cheap toaster 800w”. Query Rules can be used to filter the results by “toaster” and “prices between 0 and 25”, so that the only textual search is the remaining term, “800w”, which will further limit the results with that wattage.

Final example, “Tomato”. A simple search, but one that may never return the fruit (or vegetable) because too many Tomato Soup brands are selling better than cherry tomatoes.

With a dataset that contains both tomatoes and tomato soups, there’s currently no way for the engine to distinguish between those two items - even though we know that when people type “tomato” they are looking for the fruit and not the soup. Query Rules can help contextualize a search - that is, provide hints about what to display - by adding a filter depending on the query.

So in this example when the query is “tomato” we can add a filter “category=fruit”

We’ll describe below more technically how all of this gets done, the point here was only to illustrate how Query Rules helps to make sense of queries (cheap phone) and avoid ambiguities (tomato) - cleanly and easily.

© Algolia - Privacy Policy