Query Rules Use Cases
On this page
- What is Query Rules?
- What is Query Rules solving?
- When to use Query Rules?
- How to implement Query Rules
- Query Rules Code Samples
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.
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 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. 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.
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.
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. See how to do this.
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. See how to do this.
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.
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.
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. See how to do this.
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.
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 firstname.lastname@example.org.
Did you find this page helpful?
We're always looking for advice to help improve our documentation!
Please let us know what's working (or what's not!).
We're constantly iterating thanks to the feedback we receive.