Query Suggestions

As of May 1st, 2024, Apple requires all iOS apps to include a privacy manifest. Ensure you incorporate our provided privacy manifest files into your documentation. For more details, see Privacy Manifest.

Query Suggestions help users search by showing a list of popular searches as search suggestions as they type. By selecting suggestions, users type less and avoid searches that don’t return any results.

Users often interact with Query Suggestions in an autocomplete menu. After typing a few letters, a list of suggestions appears below the search box. Choosing a suggestion initiates a search using that suggestion as the query.

Query Suggestions can also help in these cases:

• To help users before they type anything. This is often combined with featured categories or featured search results.

• To help users continue if a search didn’t return any results.

Explore Query Suggestions user interfaces

For examples of Query Suggestions in action, see:

• Query Suggestions demo with InstantSearch.js
• Autocomplete examples with Query Suggestions

For more information about building a Query Suggestions UI, see:

• Build a Query Suggestions UI with InstantSearch
• Build a Query Suggestions UI with Autocomplete

How Query Suggestions work

Query Suggestions are stored as records in an Algolia index. This index is rebuilt every day, or when you change its settings. Each update runs through these steps:

1. Find the most frequent searches from the search analytics of your source indices and their replicas. During the early stages of your implementation, when you haven’t gathered sufficient analytics, you can also generate suggestions using external analytics or your facets.

2. Normalize and complete suggestions by removing duplicated, similar, or prefixed suggestions, depending on your settings. Suggestions must match the following criteria:

   • Only contain alphanumeric characters
   • Return a minimum number of search results
   • Longer than a minimum number of letters
   • Not be a banned expression.

   Query Suggestions also deduplicate similar searches, keeping only the most frequently searched terms as suggestions.

3. Rank the suggestions by popularity (number of searches) in the last 30 days. For all similar searches, the individual counts are summed. Counts from external analytics are also added to the suggestion’s popularity.

Each suggestion in the Query Suggestions index has at least these attributes:

• objectID. Unique identifier of the record, usually the suggestion itself
• query. The suggestion
• popularity. Number of searches in the last 30 days for the suggestion

If you add suggestions from facets, more attributes are added.

Set up Query Suggestions

1. Go to the Algolia dashboard and select your Algolia application.
2. On the left sidebar, select Search.

3. Select your Algolia index:

   

4. Open the Query Suggestions page and click New Query Suggestions Index.
5. In the Source index field, enter the name of the index with the search results and provide a name for the Query Suggestions index. You can add more source indices later.
6. Click Accept and Continue to start building the Query Suggestions index.

Augment Query Suggestions with external analytics

If you don’t have enough searches in your search analytics yet, or you want to add specific suggestions, you can upload an external index:

1. Prepare your suggestions in a JSON file. Each suggestion must have query and count attributes. The value of the count attribute is added to the value of the popularity attribute in the Query Suggestions index for that suggestion.

   You can tweak the popularity of existing suggestions by adding them to this JSON file and setting a high value for the count attribute.

   For example:

   JSON

   Copy

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

2. Import this JSON file into Algolia as a new index.

3. On the Query Suggestions page in the Algolia dashboard, select your Query Suggestions index.

4. In the Data sources section, click Enable for External Analytics and enter the name of the index with your external analytics data.

Augment Query Suggestions with facet data

If you don’t have enough data from search analytics or external analytics, Query Suggestions can generate suggestions from the combination of facet values. For example, for the facets color and brand, these Query Suggestions are generated:

• red nike
• blue nike
• red adidas
• blue adidas

Suggestions generated from facets are less relevant than those generated by search analytics since they aren’t based on popularity.

To augment your Query Suggestions with facet data:

1. Make sure that the attributes you want to use are set as searchable attributes and attributes for faceting.

2. On the Query Suggestions page in the Algolia dashboard, select your Query Suggestions index.

3. In the Data sources section, click Enable for Queries by facets.

4. Select two facet attributes and click Add attributes. Repeat for any combination of two facets for which you want to generate suggestions.

To show categories from facets in your suggestions, see Query Suggestions with categories.

Optimize Query Suggestions

After the initial setup, you can optimize your experience by using one of the following strategies.

Improve relevance

A Query Suggestions index is a regular Algolia index, so you can use the same features and settings to tune the relevance of your suggestions.

• Use Rules to adjust the suggestions based on conditions. For example, you can promote or hide specific suggestions, change the user’s query, or display a banner.

• Use synonyms to suggest similar search terms. This helps if users search for terms that aren’t in your records (but those similar terms are).

• Adjust index settings such as typo tolerance, or tokenization.

Query Suggestions with categories

You can make your suggestions more targeted by adding categories:

1. Make sure you configure your category attribute as a facet.

2. On the Query Suggestions page, select your Query Suggestions index.

3. On the Overview & Settings tab, in the Categories section, click Edit categories.

4. In the Categories attribute field, select a category you want to show. In the Show top field, select how many of the top categories to display. For example, if you select 2, the top two categories will be added to every suggestion.

How top categories are determined

Query Suggestions determines the top categories with the following algorithm:

1. Perform a “strict” search with the suggestion in the source index—without features such as prefixing or typo-tolerance.
2. Add the most frequently found category values to the facets.exact_matches attribute.
3. Get the top filters (most often applied) for this search term from analytics and add them to the facets.analytics attribute.

The category information is added to each record in your Query Suggestions index.

For your user interface, it’s better to rely on the facets.exact_matches attribute because it represents data from your index. For example, if users often filter by a specific category, but you don’t have many items in that category, they won’t see many results when accepting this suggestion.

Display categories in your UI

Once you have categorized your Query Suggestions, decide how to display them in your frontend. One option is to redirect users to an InstantSearch page on category selection. This page would automatically use the chosen category as a filter with the user’s initial query pre-filled in the search box. For an example of this, see Build a Query Suggestions UI with InstantSearch.

Remove duplicate or unhelpful suggestions

On the Query Suggestions page, select your Query Suggestions index, and adjust the following settings to improve the quality of the suggestions:

• In the Languages field, add the language of your index. This lets Query Suggestions automatically remove duplicate suggestions, for example, singulars and plurals.

• Adjust the Minimum letters setting to prevent short, incomplete suggestions. A suggestion must have at least this many letters to be included.

• Adjust the Minimum hits setting to ensure enough search results are returned. A suggestion must return at least this many search results to be included.

• On the Banned expressions tab, add expressions or patterns for excluding suggestions.

Personalize Query Suggestions

To add personalized Query Suggestions, follow these steps:

1. On the Query Suggestions page, select your Query Suggestions index.

2. On the Overview & Settings tab, in the Settings section, select Personalized Query Suggestions.

Algolia then retrieves the top 20 facet values (based on your personalization strategy) from your source index and adds new attributes to the suggestions in your Query Suggestions index for each facet defined in your personalization strategy.

Generate different suggestions for different environments

You can use analytics tags to create different suggestions for different environments, such as mobile or desktop users, or for different geographical regions.

1. Create a new Query Suggestions index with a recognizable name. For example, include the analytics tag in the name, such as products_query_suggestions_mobile.
2. After creating the index, on the Overview & Settings tab, in the Data sources section, click Manage next to Algolia Analytics API.
3. Enter the appropriate analytics tags. For example, products_query_suggestions_mobile. This only includes suggestions with specific analytics tags.

In your UI, you can then target the different Query Suggestions indices depending on the user’s device or geographical region.

Troubleshoot missing Query Suggestions

If suggestions are missing, the Query Suggestions API can help identify the issue. For example, run the following command to retrieve the most recent log entries.

$
$
$
curl -H "x-algolia-api-key: ${YourAdminAPIKey}" \
     -H "x-algolia-application-id: ${YourApplicationID}" \
    "https://query-suggestions.us.algolia.com/1/logs/${YourQuerySuggestionsIndex}"

The log entries provide the following details:

• Source indices
• Why suggestions were skipped
• The number of popular searches
• The number of suggestion candidates from facets
• The normalization process

For more information, see Get a log file.

Query Suggestions index schema

The following example shows a record from a Query Suggestions index with categories from facets.

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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
{
  "query": "phone charger",    // The suggestion
  "objectID": "phone charger", // Unique identifier
  "popularity": 2457,          // Number of searches for this suggestion in the last 30 days
  "nb_words": 2,               // Number of words in the suggestion
  "products": {                // Name of the source index
    "exact_nb_hits": 42,       // Number of search results for this suggestion
    "facets": {     
      "exact_matches": {       // Most frequent facet values found for this suggestion
        "brand": [
          { "value": "Anker", "count": 12 },  // This means 12 of the search results have "Anker" as "brand"
          { "value": "Yootech", "count": 11 },
          { "value": "TOZO", "count": 9 },
          { "value": "Aukey", "count": 4 },
          { "value": "Apple", "count": 2 }
        ]
      },
      "analytics": {          // Most frequently applied filters for this suggestion
        "brand": [
          {
            "attribute": "brand",
            "count": 347,
            "operator": ":",
            "value": "Anker"
          },
          {
            "attribute": "brand",
            "count": 203,
            "operator": ":",
            "value": "Apple"
          },
          {
            "attribute": "brand",
            "count": 152,
            "operator": ":",
            "value": "TOZO"
          },
          {
            "attribute": "brand",
            "count": 128,
            "operator": ":",
            "value": "Yootech"
          },
          {
            "attribute": "brand",
            "count": 80,
            "operator": ":",
            "value": "Aukey"
          }
        ]
      }
    }
  }
}

See also