We recently released a new version of our docs.
26 Oct 2018

Query Rules Use Cases

Query Rules - A 3-Minute Video

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

Every Algolia customer can benefit from Query Rules

Query Rules can be used by any business, in any industry, to address the same kind of issues that customers typically face with Search. Even if the details of the problem differ, the general solution is the same. For example, whether promoting a particular book, or certain fruits, or red t-shirts, or filtering content based on themes or categories, or showing only low cost or newer items - all of these situations (and a lot more) can be managed doing more or less the same thing with Query Rules. So as you read through our examples and use cases, try to see how you can adapt them to your own needs.

Please check out our Query Rules demo to see it in action.

We present here an high-level view of the feature, with a number of examples / use cases to illustrate what Query Rules can do.

For implementation details, take a look at these pages:

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 promoting results. 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. See how to do this. And here.

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 parameters based on intent (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 iPhone is searched for, place the newest version 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. See how to do this.

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. See how to do this.

Hiding hits

You can also hide hits. Your index may contain records relevant only to a specific search. For example, remove a “banana t-shirt” for the query “banana”.

Hiding follows the same syntax as promoting, omitting the ‘position’ element.

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 signaling 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. See how to do this.

Replacing words (similar to synonyms)

Our current synonym functionality expands a search by adding words with similar meanings. Query Rules offers an alternative. You can now replace words instead of adding new ones. For example, if you make “tv” a synonym for “television”, our synonym logic will expand “tv” to search with both “tv” and “television”. Query Rules allows you to replace “tv” with “television” so that only “television” is used to search.

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.

How to implement Query Rules

Using the Query Rules Dashboard

We suggest you start with the Dashboard, to understand how to work with Query Rules. The dashboard provides you with an easy interface to create and configure your rules. And importantly, you can easily test your choices live using the Dashboard’s search interface.

In fact, you might never need to go beyond the Dashboard - especially if your rules are few or they follow a very clearly defined pattern.

In this way, you can consider the Dashboard as a way to manage static rules - rules that remain in place for some time, or whose effect is global and constant.

For the Dashboard, you’ll need to go to the Query Rules tab and click on “Add Query Rule”.

Coding with the Query Rules API Client

Coding the rules using the Query Rules API becomes necessary when you need more programmatic control. This move from static to more dynamic rules can arise for a number of reasons - like when the rules become too numerous to manage one-by-one, or when you want to start building (and deleting) rules based on the content of your database and where it is possible therefore that your rules will change with every new update of your index.

For the API, you’ll need to set up your index properly, and then set up the query rules at indexing time.

Some Use-Case Videos

Merchandising with Query Rules

User Query Interpretation

Query Rules Code Samples

Check out these code and dashboard examples:


If you feel that your situation is not being addressed, send us an email at support@algolia.com.

© Algolia - Privacy Policy