## Documentation Index

Fetch the complete documentation index at: [/llms.txt](/content/llms.txt)

Use this file to discover all available pages before exploring further.

### Android

- [JavaScriptInstantSearch.js](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/js/index.html)
- [ReactReact InstantSearch](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/react/index.html)
- [VueVue InstantSearch](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/vue/index.html)
- [iOSInstantSearch iOS](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/ios/index.html)
- [AndroidInstantSearch Android](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android/index.html)

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. When typing, 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](/content/doc/guides/building-search-ui/going-further/conditional-display/android#handling-no-results/index.html).

## How Query Suggestions work

Algolia stores Query Suggestions as records in an 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](/content/doc/guides/search-analytics/overview/index.html) of your source indices and their replicas. During the early stages of your implementation, when you haven’t gathered enough analytics, you can also generate suggestions using external analytics or your facet data.
2. **Normalize and complete suggestions** by removing duplicated, similar, or prefixed suggestions, depending on your [settings](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#remove-duplicate-or-unhelpful-suggestions/index.html). 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 record identifier, 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](https://dashboard.algolia.com/explorer/browse) and select your Algolia application.
2. On the left sidebar, select **Search**.
3. Select your Algolia index.
4. Open the [**Query Suggestions**](https://dashboard.algolia.com/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 external analytics from a JSON file. External analytics give Query Suggestions another data source. They don’t replace your source index, which must contain your searchable records.

1. Prepare your suggestions in a JSON file. Each suggestion must have `query` and `count` attributes. Algolia adds the value of the `count` attribute to the value of the `popularity` attribute in the Query Suggestions index for that suggestion. To increase the popularity of existing suggestions, add them to this JSON file with a high value for the `count` attribute. For example:

```json
[
  {
    "query": "shoes",
    "count": 10031
  },
  {
    "query": "dress shirt",
    "count": 731
  },
  {
    "query": "yellow jacket",
    "count": 122
  }
]
```

2. [Import](/content/doc/guides/sending-and-managing-data/send-and-update-your-data/how-to/importing-with-the-api/index.html) this JSON file into Algolia as a new index. This index is your external analytics index.
3. Create or open the Query Suggestions index you want to enrich. If you create a Query Suggestions index, set **Source index** to the index that contains your searchable records, not the external analytics index you imported in step 2. For example, if your searchable records are in `products`, use `products` as the source index.
4. In the **Data sources** section, click **Enable** next to **External Analytics**.
5. In the **External analytics index** field, enter the name of the index you imported in step 2. For example, if you imported your JSON file into `external_query_analytics`, use `external_query_analytics` as the external analytics index.

### Augment Query Suggestions with facet data

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

- red nike
- blue nike
- red adidas
- blue adidas

Suggestions created from facets are less relevant than those created by search analytics since they aren’t based on popularity. But they can still enrich the suggestions, especially for rarer queries. That’s why it’s best to keep suggestions from facets, even after you collect sufficient data from analytics.

To augment your Query Suggestions with facet data:

1. Set appropriate [searchable attributes](/content/doc/guides/managing-results/must-do/searchable-attributes/index.html) **and** [attributes for faceting](/content/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard/index.html).
2. On the [**Query Suggestions**](https://dashboard.algolia.com/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](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#query-suggestions-with-categories/index.html).

## Optimize Query Suggestions

After the initial setup, you can optimize your experience with 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](/content/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/promote-hits/index.html) or [hide](/content/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/how-to-hide-hits/index.html) specific suggestions, [change the user’s query](/content/doc/guides/managing-results/rules/detecting-intent/index.html), or [display a banner](/content/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/add-banners/index.html).
- Use [**synonyms**](/content/doc/guides/managing-results/optimize-search-results/adding-synonyms/index.html) 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](/content/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/index.html), or [tokenization](/content/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/tokenization/index.html).

### 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](/content/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard/index.html).
2. On the [**Query Suggestions**](https://dashboard.algolia.com/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, choose a category to display. In the **Show top** field, select how many top categories to display. For example, if you chose `2`, the top two categories are added to every suggestion.

#### How to determine top categories

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`](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#query-suggestions-index-schema/index.html) attribute.
3. Get the top filters (most often applied) for this search term from analytics and add them to the [`facets.analytics`](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#query-suggestions-index-schema/index.html) 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 uses 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](/content/doc/guides/building-search-ui/ui-and-ux-patterns/autocomplete/vue/index.html).

### Remove duplicate or unhelpful suggestions

On the [**Query Suggestions**](https://dashboard.algolia.com/query-suggestions) page, select your Query Suggestions index, and adjust the following settings to improve the quality of the suggestions:

1. In the **Languages** field, add the language of your index. This lets Query Suggestions automatically remove duplicate suggestions such as singulars and plurals.
2. Adjust the **Minimum letters** setting to prevent short, incomplete suggestions. A suggestion must have at least this many letters to be included.
3. 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.
4. On the **Banned expressions** tab, add expressions or patterns for excluding suggestions.

### Personalize Query Suggestions

To add [personalized](/content/doc/guides/personalization/classic-personalization/what-is-personalization/index.html) Query Suggestions, follow these steps:

1. On the [**Query Suggestions**](https://dashboard.algolia.com/query-suggestions) page, select your Query Suggestions index.
2. On the **Overview & Settings** tab, in the **Settings** section, enable **Personalized Query Suggestions**.

Algolia then retrieves the top 20 facet values (based on your [personalization strategy](/content/doc/guides/personalization/classic-personalization/personalizing-results#configure-your-personalization-strategy/index.html)) 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](/content/doc/guides/search-analytics/guides/segments/index.html) 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](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#set-up-query-suggestions/index.html) 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 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: $ALGOLIA_ADMIN_API_KEY" \
     -H "x-algolia-application-id: $ALGOLIA_APPLICATION_ID" \
    "https://query-suggestions.us.algolia.com/1/logs/$ALGOLIA_QUERY_SUGGESTIONS_INDEX"
```

The log entries provide the following details:
- Source indices
- Why suggestions were skipped
- The number of [popular searches](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#how-query-suggestions-work/index.html)
- The number of suggestion candidates from [facets](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#augment-query-suggestions-with-facet-data/index.html)
- The [normalization](/content/doc/guides/building-search-ui/ui-and-ux-patterns/query-suggestions/android#how-query-suggestions-work/index.html) process

For more information, see [Get a log file](/content/doc/rest-api/query-suggestions/get-log-file/index.html).

## Query Suggestions index schema

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

```json
{
  "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"
          }
        ]
      }
    }
  }
}
```