Query Suggestions in React InstantSearch Hooks

Query Suggestions is a search experience that displays a list of possible queries that your users can select from as they type. This pattern exists on popular sites such as Google and Amazon, so users expect it from a search experience.

Query Suggestions help users find queries that are guaranteed to return results. They help users type less, which is especially impactful on mobile.

The term “query suggestions” refers to the textual suggestions themselves. The terms “autocomplete” or “dropdown” refer to the UI that your users use to interact with suggestions. An autocomplete could display search results rather than suggested searches.

Query Suggestions are different from search results. Query Suggestions are only suggestions of better queries. When typing “smartphone”, a user may receive a suggestion to pick a more precise query, such as “smartphone apple” or “smartphone iphone xs”, which would retrieve more specific results.

A typical implementation is to retrieve Query Suggestions at each keystroke, so that you can display them on your front end for the user to select. When they do, they land on a page with the results of the suggested query. To get a sense of what this looks like, check out the tutorial on building this experience.

Another common experience is to display suggestions and results together in a single autocomplete menu. There could even be multiple results sections, for example for products, categories, brands, articles, or blog posts. Each of these results sections comes from a search into a different index or from a search for facet values. Refer to the guides on how to include multiple result types in your autocomplete and multi-index search for more information.

Current Standard and Premium plans give you access to a Query Suggestions tab in your Algolia dashboard. Please reach out to the support team if you have any problems accessing Query Suggestions.

Implementing Query Suggestions

The Query Suggestions feature works by building a new index that automatically updates based on how your end users search. As with any other index, you need to build the UI which your users will use to interact with the index, and you can also optimize relevance by configuring index settings.

There are three main implementation steps:

1. Creating your Query Suggestions index configuration. The Query Suggestions section of the Algolia dashboard is specifically designed for this but you can also use the Query Suggestions REST API to create and edit configurations. Once you’ve configured your new Query Suggestions index, the feature starts building suggestions based on the source index (the one that contains your search results). Creating a Query Suggestions index configuration requires an understanding of your current Algolia implementation, such as which indices contain what data, and what types of analytics you have access to.
2. Building a UI for your Query Suggestions index. For this step, you can use libraries such as Autocomplete and InstantSearch. Building UI requires front-end development.
3. Optimizing your Query Suggestions index’s relevance with Rules, synonyms, and other index settings. This is also most easily accomplished from the dashboard. This step requires an understanding of what suggestions you expect to see and how you want to prioritize them from a business standpoint.

Beyond these essential steps, you can take your implementation further by adding categories to your suggestions and personalizing your suggestions to individual users.

How Query Suggestions works

Once you’ve configured your new Query Suggestions index, the feature starts filling it with suggestions. These suggestions don’t come out of nowhere—they’re a result of how your users interact with your search experience.

Data-driven suggestions

By default, suggestions leverage Analytics data. Specifically, the Query Suggestions builder pulls the most frequent searches from the designated source index and its replica indices. The source index is the index that contains your search results. For example, if you have a products index which you want to generate suggestions for, this is the source index. You can also specify multiple source indices if you want to pull suggestions from multiple indices’ analytics.

For each popular search term, the Query Suggestions builder checks to see if it returns results in the source index. If it does, the builder includes it in the Query Suggestions index. By using only the top searches leading to results, the builder ensures that users always get results when they select a suggestion. Query Suggestions only include the most popular queries and not those on the long tail.

Since suggestions are based on your Algolia analytics, the more traffic you have, the more suggestions the Query Suggestions builder can generate. Users without much traffic or with large catalogs may want to supplement suggestions with external analytics. If you haven’t generated enough Algolia Analytics yet and don’t have external analytics to rely on, you can use facet data to create suggestions.

Suggestion normalization and completion

The Query Suggestions builder normalizes and completes suggestions to remove duplicated, similar, and prefixed suggestions. You can also customize a set of configurable constraints that disqualify search terms from your suggestion index. The builder doesn’t include a search term as a suggestion if it matches any of these criteria:

• Suggestion contains non-alphanumeric characters
• Suggestion doesn’t meet the minimum number of results configured when querying a given source index
• Suggestion length doesn’t meet the minimum number of letters configured
• Suggestion matches any of the banned expressions configured

Although top searches taken from the Analytics API are already aggregated, the Query Suggestions builder further normalizes and completes suggestions. For example, consider these four potential suggestions are top searches in the source index: “tablets”, “Tabl”, “Tablets”, “tablet”. The builder only keep the one with the most searches. For the most pertinent normalization, it’s important to set the language in your Query Suggestions configuration. You can also remove popular but irrelevant or inappropriate searches by configuring banned expressions.

Ranking suggestions by popularity

The Query Suggestions builder give each suggestion a popularity score based on the number of times the term was searched for in the last 30 days by unique users. To take normalization into account, the builder sums the count for all suggestions that it’s aggregated into one. For example, if the builder aggregates “tablets”, “Tabl”, “Tablets”, and “tablet” into the single suggestion “tablet”, it sums the counts of all four initial suggestions to compute the popularity score for “tablet”. The builder also sums the counts with any suggestions you include in external analytics, then uses this score in the suggestion index’s customRanking to rank results by relative popularity.

Each suggestion in a Query Suggestion’s index has at least the query (the suggested search term) and popularity attributes:

1
2
3
4
{
  "query": "iphone X",
  "popularity": 255
}

Keeping your suggestions up-to-date

To ensure that the suggestions the Query Suggestions builder generates reflect your users’ search trends, it rebuilds the index once every 24 hours, or whenever you change and save your suggestion index’s configuration. Since Query Suggestions always take the last 30 days into account, your suggestions index is based on a sliding window of the most recent analytics data. Time decay doesn’t play a role in the popularity of suggestions. In other words, searches made earlier in the last 30 days don’t count less than searches made more recently when calculating a suggestion’s popularity.