Create a Query Suggestions index for React InstantSearch

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

A Query Suggestions index contains vetted search suggestions with a popularity score. Use the Query Suggestions page on the dashboard to configure your Query Suggestions.

When creating a Query Suggestions index, you need to consider the data source or sources for the suggestions. By default, the Query Suggestions builder generates suggestions by leveraging data from your Search Analytics. Specifically, the builder pulls the most frequent searches from the last 30 days from the designated source index. It applies a distinct userToken per search policy when computing search frequency.

You can also use external analytics or facet data to supplement your suggestions index. If you opt to use external analytics or facet data, you must still begin by creating a Query Suggestions index configuration based on Algolia Analytics.

Using Algolia Analytics

To see if you can rely on Algolia Analytics data alone, take a look at the Searches in the analytics dashboard for the last 30 days, for your source index. The source index is the index you want to rely upon to generate the suggestions index. The source index’s top searches can give you a rough idea of generated suggestions—rough, because the Query Suggestions builder normalizes, completes, and vets suggestions to ensure they fetch results and meet all your quality criteria.

Even if your source index’s analytics don’t (yet) have many searches, it’s still necessary to start by setting up your Query Suggestions configuration to reference a source index. In addition to analytics, the Query Suggestions builder uses the source index to vet and normalize suggestions and extract facet and category information.

Using the dashboard

1. Select the Search product icon on your dashboard.
2. Navigate to the Query Suggestions page in the left sidebar menu of the dashboard.
3. Click the New Query Suggestions Index button on the top right.
4. A new page appears. Enter the Source index name here. The source index is the index whose analytics data you want to rely upon to generate the suggestions index. This step is mandatory, even if you include other data sources.
5. The input autofills the Name for the new Query Suggestions index with the source index’s name postfixed with “_query_suggestions”, but you can edit it as you see fit. Be sure to not use an existing index’s name. Doing so overwrites this index.
6. Read the analytics processing information and click Accept and Continue if you agree.

As soon as you have completed these steps, you’ll land on your suggestion index’s Query Suggestions configuration page. From here, you can configure your suggestions and add extra data sources. The Query Suggestions builder begins building your Query Suggestions index right away, but it’s best to spend some time configuring your index.

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

Filtering on analyticsTags

When using Algolia Analytics as a data source, you have the option to extract suggestions based only on searches with certain analyticsTags. For example, if you want to generate separate suggestions for mobile and desktop users, and you already have mobile and desktop searches appropriately tagged, you can create two separate suggestions indices: one where only searches tagged with mobile are used to generate suggestions and one where only searches tagged with desktop are used.

1. Navigate to the Query Suggestions page in the left sidebar menu of the dashboard.
2. Click the New Query Suggestions Index button on the top right.
3. A new page appears. Enter the Source index name here.
4. The input autofills the Name for the new Query Suggestions index with the source index’s name postfixed with “_query_suggestions”, but you can edit it as you see fit. In this case, it makes sense to add the analyticsTags to the name, for example, “products_query_suggestions_mobile”.
5. Read the analytics processing information and click Accept and Continue if you agree. This will take you to the Query Suggestions configuration page.
6. In the Data Sources section, click Manage next to Algolia Analytics API.
7. In the modal that appears, enter the name or names of the analyticsTags to add. In this example, since the goals is to separate suggestions for mobile and desktop, add one analyticsTags per index configuration. For “products_query_suggestions_mobile”, use the mobile analyticsTags.
8. Repeat the process to create a new suggestion index, for example, “products_query_suggestions_desktop”, which filters suggestions to only include searches made with the desktop analyticsTags.

Following these steps results in separate Query Suggestions indices for different analyticsTags. Then, on the frontend, you can target the different indices depending on the user’s device. To do so, you can reuse the same logic that you used to send the appropriate analyticsTags.

Adding multiple source indices

If you’d like to extract suggestions from multiple indices’ analytics into one suggestions index, you can do so from your suggestions index’s Query Suggestions configuration page, after you’ve already set up the initial source index.

1. Navigate to the Query Suggestions page in the left sidebar menu of the dashboard.
2. Select the Query Suggestions index you want to add source indices to by clicking its name or the Edit button with the pencil on the right side.
3. Next to Source indices settings select the Add button.
4. In the modal that appears, enter the name of the additional source index and click Add.
5. Repeat this for as many additional source indices as you would like.

Using external analytics

If you don’t have enough Algolia Analytics to build a robust suggestions index or if you want to add specific suggestions or tweak a suggestion’s popularity, you can add custom suggestions. You must first add these custom suggestions to a separate Algolia index dedicated for this purpose.

In selecting which queries to suggest, you can either add what you consider “ideal” queries, or use analytics data from other sources, for example, Google Analytics or Segment. The only requirement is that the data must have the same format as Algolia’s analytics data. This is necessary because the Query Suggestions builder combines this data with Algolia Analytics from the source index, even if there is little Algolia Analytics data.

The Query Suggestions builder vet and normalize suggestions from an external analytics index in the same way as suggestions from Algolia Analytics. This means, for example, that if an external analytics suggestion doesn’t retrieve the minimum number of results in the source index, the builder won’t include it in the suggestions index.

Expected external suggestions format

External suggestions require only query and count fields. The query is the suggestion you would like to add and the count is a measure of its relative popularity, which the Query Suggestions builder uses when calculating popularity in the suggestions index.

If you would like to tweak the popularity of an already existing suggestion, add the suggestion to the external analytics index and give it a high count. The Query Suggestions builder sums this with the count from Algolia Analytics when computing the popularity metric.

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
  }
]

Suppose you are extracting suggestions from another source: It’s necessary to reformat them in this way, either by manually creating a JSON file or writing a script that transforms the data into this format and pushes it to Algolia. You can also complete this entirely from the dashboard.

Using the dashboard

1. Navigate to the Indices page of the dashboard.
2. Click the Create Index button on the top right.
3. Enter the name of the new index. It’s best to use something like “products_query_suggestions_external_analytics” to make it clear what the purpose of the index is.
4. A sidebar appears on the right of the screen. Click the Upload record(s) drop-down menu and select either Add manually or Upload file if you have a pre-formatted JSON file with your suggestions. You can select Use the API if you are comfortable using the API clients.
5. If you selected Add manually, copy and paste the pre-formatted JSON suggestions records into the input field below Add your records here. Click Save.
6. If you selected Upload file, drag or select a pre-formatted suggestions file, with the preceding format.
7. Regardless of how you import your records, exit the task list by clicking the Close side panel (X) button in the top right. External analytics indices don’t require searchableAttributes or customRanking.
8. Navigate to the Query Suggestions page in the left sidebar menu of the dashboard.
9. Select the Query Suggestions index you want to supplement by clicking its name or the Edit button with the pencil on the right side. If you haven’t set up the Query Suggestions index, do so first.
10. Under Data Sources, click the Enable button to the right of External Analytics. A modal appears prompting you for the name of the external analytics index. This example uses “products_query_suggestions_external_analytics”.
11. Click the Save button on the bottom right corner of the screen.

As long as your external analytics index is listed as an External Analytics source, the Query Suggestions builder refers to the external analytics index each time it rebuilds the Query Suggestions index. If you update your external analytics index, the builder takes the updated suggestions into account the next time it builds the Query Suggestions index, at least once every 24 hours.

If you plan on regularly updating your external analytics index, it’s most efficient to develop a script to do this using one of the API clients.

Using facet data

If you have neither Algolia nor external analytics to build your suggestions, you can generate suggestions based on the facets in your source index. For example, if you choose the facets “color + brand”, the Query Suggestions builder generates a suggestion for every color and brand combination:

• “red nike”
• “blue nike”
• “red adidas”
• “blue adidas”
• …

The Query Suggestions builder bases the popularity score for these suggestions on the amount of items that match the query.

You should only use this method when you have no initial data—neither Algolia Analytics nor your own suggestions. In the long run, these facet-based suggestions become less relevant, that is, less popular, than your analytics-based ones.

You must declare attributes you want to use to generate suggestions as attributesForFaceting and as searchableAttributes.

Using the dashboard

1. Navigate to the Indices page of the dashboard.
2. Select your source index. This isn’t your Query Suggestions index—it’s the index you selected when first setting up your Query Suggestions index. If you haven’t done this, set up a Query Suggestions index first.
3. Navigate to the source index’s Configuration > Filtering and Faceting > Facets page.
4. If not already done so, add the attributes you want to use to generate suggestions as attributesForFaceting. If you are only using the attributes to generate suggestions, you can make them filterOnly to optimize performance.
5. Navigate to the source index’s Configuration > Relevance Essentials > Searchable attributes page.
6. If not already done so, add the facets you want to use to generate suggestions as searchableAttributes. To have the minimum impact on relevance, you can add them as the last searchableAttributes. If you are only using the attributes to generate suggestions, you can add them to disablePrefixOnAttributes to optimize performance.
7. Navigate to the Query Suggestions page in the left sidebar menu of the dashboard.
8. Select the Query Suggestions index you want to supplement by clicking its name or the Edit button with the pencil on the right side.
9. Under Data Sources, click the Enable button to the right of Queries by facets. A modal appears prompting you for the facets you would like to use.
10. If you would like to combine two or more facets together to generate a suggestion, for example, “blue adidas”, add them together in one input using the Add attributes button.
11. Add any relevant facets or combinations of facets that would work as suggestions. Consider these carefully: some facets, such as “category”, may be worthwhile suggestions in and of themselves. Others, such as “color”, may not create relevant suggestions on their own and should be used together with other facets. When finished, click Confirm.
12. Click the Save button on the bottom right corner of the screen.

Once you’ve added facet data as a source of suggestions, the Query Suggestions builder begins adding facet-based suggestions to your index. You shouldn’t expect the builder to add every single facet value or combination of values. Since the builder can fetch a maximum of 1000 values per facet, it may not include all values for attributes with high cardinality. The builder also still vet suggestions generated by facet values by ensuring that they fetch results and meet other configuration options.

Facet-based suggestions all have a score of zero for popularity. The popularity score is based on how often users search for a particular query. Since the Query Suggestions builder generate these suggestions based on facet data alone, it can’t calculate such a metric. This is one reason you should only use this suggestion generation method if you have neither Algolia Analytics nor external analytics to rely on.

Configuration options

By default, the Query Suggestions builder indexes all popular searches that meet the default configuration values as suggestions. Without configuration, suggestions can be redundant, irrelevant, or even embarrassing. One non-Algolia powered company, for example, once received a flood of phony, inappropriate searches, which, due to their popularity, ranked higher than other searches. This meant that other users began to see these phony searches. It’s a real concern that you want to address.

Query Suggestions has four configurable options in place to limit redundant, irrelevant, or inappropriate suggestions.

Languages

Though optional, setting the language or languages for your Query Suggestions index configuration improves the quality of suggestions. The Query Suggestions builder uses the setting to deduplicate singular and plural suggestions in the normalization process. For example, if you set the Query Suggestions language to English, and two top searches on the source index are “shoe” and “shoes”, the builder only keeps the more popular of the suggestions. Without setting languages, you could have redundant suggestions.

Minimum letters

This is the minimum number of letters a popular search must have to consider it as a relevant suggestion. The default value is four—that helps keep short, incomplete suggestions from appearing.

Minimum hits

By default, the suggestions index only includes search terms that return at least five results in the source index. You can configure this from your Query Suggestions index’s configuration page. The higher the number, the more results a potential suggestion must return for the Query Suggestions builder to include in the suggestions index.

Banned expressions

Banned expressions is the most powerful and direct way to restrict inappropriate or irrelevant suggestions. Banned expressions is a list of suggestions the Query Suggestions builder will never include in your suggestions index, regardless of their popularity. You can configure this list by navigating to the Query Suggestions page and selecting the Query Suggestions index you want to add this list to. On the index’s main configuration page, select Banned expressions under the top header, next to Overview & Settings.

Here you can add either exact or partial matches for the engine to ignore. Use the Query is option for exact matches, and Query contains, Query starts with, Query ends with, or Matches regExp for partial matches. The Matches regExp qualifier expects a regular expression.

Computing popularity

In addition to these configurable values, the Query Suggestions builder uses a distinct userToken per query policy. This means when a userToken sends many similar queries, only one of those queries counts towards the popularity of its related suggestion. This prevents an accidental or abusive flood of requests from the same userToken. This restriction can’t be removed or configured.

To have the most accurate normalization and popularity calculation, be sure to set the userToken for searches made to your source index.

Suggestions index schema

Once you’ve selected the data sources and configured your Query Suggestions index, the Query Suggestions builder automatically starts generating suggestions. This process can take up to a few hours for large indices. The index’s Query Suggestions configuration page shows the Status “The index is ready” once index has been built, as well as the Last build time.

The Query Suggestions index contains suggestions as records with the following schema:

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
33
34
35
36
37
38
{
  "query": "chamber of secrets",  // suggestion text
  "objectID": "chamber secrets",  // unique identifier
  "popularity": 186,  // estimated number of users that searched for the query or related forms in the last 30 days
  "nb_words": 3,  // number of words in the suggestion
  "products": {  // source index name
    "exact_nb_hits": 5,  // number of results for the suggestion in the source index
    "facets": {
      "exact_matches": {
        // information regarding the most frequent facet values
        // appearing in the results for the search term
        "media_type": [
          {
            "count": 1,
            "value": "movie"
            // this combination of "count" and "value" means one of the five results
            // for the search "chamber of secrets" had the media_type "movie"
          }
        ]
      },
      "analytics": {
        // information regarding the most often used filters with this search
        "media_type": [
          {
            "attribute": "media_type",
            "count": 142,
            "operator": ":",
            "value": "movie"
            // this combination of attribute, count, operator, and value means
            // that of 186 searches for "chamber of secrets" on the source index,
            // 142 included the filter "media_type:movie"
          }
        ]
      },
    }
  }
}
}

A suggestion record always includes the query, objectID, popularity, and nb_words attributes. The query is the suggestion text to display in the UI. The Query Suggestions builder uses popularity for ranking purposes. The objectID is the unique identifier for the suggestion. While it may often be the same as the query, this isn’t guaranteed.

If you’ve selected to add categories to your suggestions, the Query Suggestions builder also includes information about the top categories nested in source index attribute (here products). For more information about these attributes, refer to Suggestions with categories index schema.

Default index settings

These are the default index settings for a Query Suggestions index:

1
2
3
4
5
6
{
  "searchableAttributes": ["query"],
  "customRanking": ["desc(popularity)"],
  "attributesToHighlight": ["query"],
  "numericAttributesForFiltering": ["nb_words"]
}

Whenever your Query Suggestions index rebuilds, the Query Suggestions builder preserves any index settings changes you’ve made. Check out the guide on optimizing Query Suggestions relevance to see why you may want to change index settings or add Rules and synonyms.

Next steps

Once you’ve created a Query Suggestions index configuration, you’re on your way to implementing one of the most popular and user friendly search experiences.

The next step is to build a UI for your suggestions index. You can also optimize your index’s relevance with Rules, synonyms, and other index settings.

To take your Query Suggestions implementation further, you can consider adding category information to suggestions and personalizing suggestions to individual users’ preferences.