Guides / Building Search UI / UI & UX patterns / Query Suggestions

Troubleshoot Query Suggestions with InstantSearch.js

On this page

Sometimes, you may find that a suggestion you expect to be in your Query Suggestions index is missing. If this occurs, the logs endpoint in the Query Suggestions REST API can help you understand why.

You can retrieve the log file for the last build of any Query Suggestions index using the logs endpoint. When the request is successful, the HTTP response is a 200 OK and returns the most recent log file in JSON Lines format. Depending on the amount of source data considered for suggestions, the logs can be quite large. It may be easiest to dump the response into a file for further inspection.

Copy 
1
2
3
4
5
6

curl -X GET \
     -o "path/to/logs.jsonl" \
     -H "X-Algolia-API-Key: ${YourWriteAPIKey}" \
     -H "X-Algolia-Application-Id: ${YourApplicationID}" \
     --compressed \
    "https://query-suggestions.us.algolia.com/1/logs/${query_suggestions_index_name}"

You must use the Admin API key to access Query Suggestions build logs.

Log schema

Each line in the log file is a single log and has the following attributes:

  • timestamp - date and time of logged action.
  • level - type of log, can be one of three values: INFO, SKIP, or ERROR.
  • message - detailed description of what happened.
  • contextLevel - the hierarchy of the logs. For example, a log with contextLevel=1 belongs to a preceding log with contextLevel=0.

Sample log file

Logs include information about the generation process as a whole, including:

  • What source indices the Query Suggestions builder used, including external analytics sources
  • Number of top searches found in the source index’s analytics
  • Number of suggestion candidates from facet data
  • How many read and write operations the Query Suggestions builder made to generate the suggestions

See below for examples of these types of logs:

Copy 
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

[
  {
    "timestamp": "2020-11-03T04:10:59.200274859Z",
    "level": "INFO",
    "message": "done loading analytics data in 2.995576317s",
    "contextLevel": 0
  },
  {
    "timestamp": "2020-11-03T04:11:00.525440213Z",
    "level": "INFO",
    "message": "about to process source index \"instant_search\"",
    "contextLevel": 0
  },
  {
    "timestamp": "2020-11-03T04:11:02.801832802Z",
    "level": "INFO",
    "message": "found 515 popular searches",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:20.95248061Z",
    "level": "INFO",
    "message": "0 potential candidates for generation from facets",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:20.952486251Z",
    "level": "INFO",
    "message": "about to import external indices",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:20.952491864Z",
    "level": "INFO",
    "message": "done to processing source index \"instant_search\"",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:29.967979293Z",
    "level": "INFO",
    "message": "done generating suggestion index \"query_suggestions\" in 29.44254095s",
    "contextLevel": 0
  },
  {
    "timestamp": "2020-11-03T04:11:29.968089323Z",
    "level": "INFO",
    "message": "1,023.00 reads and 313.00 writes made to the searchAPI",
    "contextLevel": 0
  }
]

Skipped suggestions

In addition to general information about the generation process, logs include why particular candidate suggestions were “skipped,” and not included in the suggestions index. This often has to do with configuration options, such as the minimum number of results a suggestion must retrieve or the minimum number of letters a suggestion must have. If you find that a desired suggestion was skipped for one of these reasons, you can change your configuration accordingly.

Copy 
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

[
  {
    "timestamp": "2020-11-03T04:11:02.801865892Z",
    "level": "SKIP",
    "message": "skipping query \"\": the query is empty",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:02.852462339Z",
    "level": "INFO",
    "message": "skipping query \"a\": not enough letters",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:03.488965905Z",
    "level": "SKIP",
    "message": "query \"apple airport\" does not meet the min hits criteria of 5, got 4 hits",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:03.488965905Z",
    "level": "SKIP",
    "message": "skipping query \"query\": not enough search results with prefixNone index, got 0, expected 5",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:03.488965905Z",
    "level": "SKIP",
    "message": "skipping query \"3-year\": excluded because containing a special char",
    "contextLevel": 1
  }
]

Normalization

To avoid redundant suggestions, the Query Suggestions builder normalizes and completes suggestions based on the configured language. In the example below, you can see the builder doesn’t always use the singular or plural. Instead, it only keeps the most popular declined form.

Copy 
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

[
  {
    "timestamp": "2020-11-03T04:11:02.852462339Z",
    "level": "INFO",
    "message": "normalized \"clou\" to \"cloud\"",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:20.952497284Z",
    "level": "INFO",
    "message": "about to normalize plurals",
    "contextLevel": 0
  },
  {
    "timestamp": "2020-11-03T04:11:23.37891251Z",
    "level": "INFO",
    "message": "merged \"batteries\" into \"battery\"",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:25.860366236Z",
    "level": "INFO",
    "message": "merged \"cell phone\" into \"cell phones\"",
    "contextLevel": 1
  },
  {
    "timestamp": "2020-11-03T04:11:26.614469772Z",
    "level": "INFO",
    "message": "done normalizing plurals",
    "contextLevel": 1
  }
]

Errors

When the request isn’t successful, the HTTP response could be a 404 if no Query Suggestions index exists with the given name or if the index hasn’t finished its initial build. If you use incorrect credentials or use a non-Admin API key, the API returns a 403 HTTP response.

If the request is successful, you may see some logs with level=ERROR for the reasons listed below.

During index generation

  • One of the source indices doesn’t exist
  • Can’t process source index
  • Can’t normalize plurals
  • Can’t select display forms
  • Can’t create new suggestions index
  • Unable to add external searches to suggestions index
  • Search or indexing operations quotas exceeded
  • Can’t finish generating index
  • Can’t get popular searches
  • Can’t add popular searches to suggestions index

When using external analytics

External analytics issues include:

  • Can’t browse external index, it doesn’t exist
  • Can’t get popular searches from records in external index; this is often due to incorrectly formatted data

When generating searches from facet data

Facet data issues include:

  • Can’t generate searches
  • Unable to add generated searches to suggestions index

If you receive one of these errors and don’t understand the reason behind it, reach out to your success team or contact the Algolia support team.

Did you find this page helpful?
InstantSearch.js v4