Guides / Getting insights and analytics / Leveraging analytics data / Query Suggestions

Implementing Query Suggestions

Query Suggestions are available to all Starter and Premium plans. Implementing it involves two steps:

  1. Building your query suggestions index through the dashboard,
  2. Configuring your front end to display suggestions.

Creating your suggestions index

Before creating a Query Suggestion index, there are two things to consider:

  • The data source(s) you want to use to generate suggestions,
  • The expected format, and settings of your suggestions.

You can create your Query Suggestion index in two steps:

  1. Click on the Query Suggestions tab of your dashboard and click the New Query Suggestions button.
  2. Select your source index and name your suggestions index, then click Accept and Continue.

After completing these two steps, you’ll be brought directly to your suggestions index’s main page. From here you can add extra data sources and configure your suggestions.

You can create up to 100 different query suggestion configurations per application.

To get back to your Query Suggestions index’s page, simply click on the Query Suggestions tab and select your suggestions index by its name.

Adding data sources

By default, your Query Suggestions index is generated from your Algolia Analytics data. If you don’t have Algolia Analytics data yet, your suggestions index will initially be empty. However, there are two ways that you can add initial query suggestions data and extend your Algolia Analytics.

Adding external analytics

You can add external analytics in a couple of steps:

  1. Go to the indices tab of your dashboard and create a new index by clicking on the on the New button and selecting index.

  2. Click on the Add records button, and upload your analytics data. It should contain a list of query, popularity pairs:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    
    [
      {
     "query": "shoes",
     "count": 10031
      },
      {
     "query": "dress shirt",
     "count": 731
      },
      {
     "query": "yellow jacket",
     "count": 122
      }
    ]
    
  3. On the page for your Query Suggestions index, find the Data sources menu and click the Enable button next to External Analytics option.

  4. Enter the name of the external analytics index you created and click Save.

Adding queries by facets

You can generate query suggestions based on your facets in a couple of steps:

  1. On your Query Suggestions index page, find the Data sources menu and click the Enable button next to External Analytics option.
  2. In the modal that pops up, type in the facets you want to generate suggestions from.

At this point, your facet-generated suggestions are automatically created.

The generation process puts together various facet value combinations and assigns popularity according to the number of records matching those combinations.

Configuring suggestions

There are a set of configuration options for your Query Suggestions index.

General configuration options

You can configure the following options directly from the main page of your Query Suggestions index:

  • Languages: the language(s) of your source index (helps in deduplicating and normalizing your suggestions),
  • Minimum Letters: the minimum number of letters for a suggested query,
  • Minimum Hits: the minimum number of hits a suggested query must return.

Banned expressions

You can prevent certain words from appearing in your suggestions through the Banned expressions page of your Query Suggestions tab:

  1. Click on the Start banning expressions button,
  2. Type in a single expression, a comma-separated list, or a regex string,
  3. Click Save.

Queries containing any of the terms or patterns in your banned expressions list are excluded from your suggestions index.

Category suggestion

We have a separate guide on adding category and scope to suggestions.

Resulting suggestions

Once you’ve selected the data sources and configured your suggestions, the suggestions engine automatically starts generating them. This process can take up to a few hours for large indices. Once generated, the suggestions index contains suggestions as records that you can use in your front-end implementation.

Here’s what a suggestion record can look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "query": "apple watch",
  "objectID": "apple watch",
  "popularity": 186,
  "nb_words": 2,
  "brand": [
    "Apple"
  ],
  "products": {
    "exact_nb_hits": 5
    "facets": { 
      "analytics": {
        "brand": [
          {
            "attribute": "brand",
            "count": 18,
            "operator": ":",
            "value": "Apple"
          }
        ]
      },
      "exact_matches": {
        "brand": [
          {
            "count": 5,
            "value": "Apple"
          }
        ]
      }
    }
  }
}

The objectID is the same as the query, as they’re unique in a suggestions index. This guarantees that the objectID doesn’t change between updates. The popularity attribute is the sum of all the ones specified in the data sources for the suggestion and its plural variations. The nb_words attribute represents how many words the suggestion consists of.

When personalizing Query Suggestions, records contain the facets defined in the Personalization strategy (here brand) that are associated with the top values contained in the hits that match the query in the source index.

We also include some information associated with the source index (here products) when facets have been specified in the configuration as data source. The attribute exact_nb_hits represents the number of exact hits for the query in the index. Within facets, the attribute analytics contains, for each facet, an array with the top filters used in the searches, along with the query and their associated counts. The attribute exact_matches contains, for each facet, an array with the top attributes associated with the matching hits.

Displaying suggestions

There are a number of ways you can go about implementing the front end for Query Suggestions. We briefly detail some of the options below.

Combining InstantSearch with Query Suggestions

A particularly advanced and useful UI combines the power of Query Suggestions with InstantSearch results. This would mean that, as the user types, two areas of the screen change: queries are suggested and new results appear.

Seeing both suggested queries and results can help users make search decisions. To see how this looks, check out our InstantSearch with Query Suggestions demo.

Combining suggestions and results in the same drop box

Another display option is to combine suggestions and results within the same dropdown box. This is an especially effective UI for mobile. Check out our Android Query Suggestions guide and iOS Query Suggestions guide.

Did you find this page helpful?