Reviewing query suggestion candidates

This is for:

Developer System Administrator

Coveo Machine Learning (Coveo ML) Query Suggestion (QS) models suggest the most relevant queries that were previously performed by other users. To learn more about this model type, see About Query Suggestions.

To prevent infrequent queries from polluting the suggestions, Coveo ML QS delivers suggestions only for queries that were performed and followed by at least one click on search results.

Note

To ensure optimal performance, a QS model limits the number of possible suggestions per language to a preset maximum. The limit is enforced after the most relevant query suggestions are identified and ranked, and after any manually defined default query suggestions are applied. The enforced limit is large enough to not negatively impact the quality of the suggestions. The most relevant suggestions are always recommended to the user, regardless of the enforced limit. The limit, however, may explain why a query that appears as a candidate in your data isn’t suggested for a given user query.

The required number of times the query must be performed and followed by a click varies based on the number of queries per search hub (origin level 1), search interface (origin level 2), and language in the model. The query count is relative to the model data period (for example, the number of queries that were performed in the last month).

The following table lists diverse query counts and the respective minimum number of times a specific query must be performed and followed by a click for this query to be selected as a potential suggestion. The data displayed in the table is for the period of data gathered by the model, which is set by the user.

Query count Minimum number of times a given query must be performed and followed by a click[1]

0 to 33,749

1

33,750 to 156,249

2

156,250 to 428,749

3

428,750 to 911,249

4

911,250 to 1,663,749

5

1,663,750 to 2,746,249

6

2,746,250 to 4,218,749

7

4,218,750 to 6,141,249

8

6,141,250 to 8,573,749

9

8,573,750 to 11,576,249

10

Review query suggestion candidates

Before enabling Coveo ML QS, you may wonder which queries logged by Coveo Usage Analytics (Coveo UA) from a given search interface would be candidates for query suggestions, basically ensuring that there are queries matching the minimum requirements. This verification is particularly useful when your search interface has low traffic, such as in the case of a search interface only accessible to employees in a small company.

You can use the Analytics section of the Coveo Administration Console navigation menu to list queries that match the minimal QS requirements. You can then establish whether Coveo ML QS can have a significant impact on a specific search interface for a specific language.

Note

You can review the top queries suggested by your model by going on the Models (platform-ca | platform-eu | platform-au) page of the Coveo Administration Console, and looking at the Information section of your specific model.

This section contains a procedure that shows how to create a dashboard displaying the queries that meet the requirements to be suggested by a Coveo ML QS model for a specific search interface (that is, queries that were performed and followed by a click the required number of times). The following procedure assumes that you’re familiar with global dimension filters and dashboards (see Add global dimension filters and Review and manage dashboards).

You could also build a dashboard using a JSON configuration. If you want to create the dashboard using the Usage Analytics Read API, see Review query suggestion candidates using the Usage Analytics Read API.

Note

You may want to report on the suggested queries that have been clicked by users. You can do so by reporting on the search events for which the Event Cause has the omniboxAnalytics value.

  1. On the Reports (platform-ca | platform-eu | platform-au) page, click Add, and then select Blank dashboard.

  2. In the empty report that appears, in the upper-left corner of the screen, enter a title for the dashboard (for example, Queries Suggested by Coveo ML).

  3. (Optional) Enter a dashboard description.

  4. Select a date interval of three months (see Set the period to review search usage data).

  5. Add the following global filters (see Add global dimension filters):

    • User Query is not blank or n/a

    • Origin 1 (page/hub) is <SEARCH_PAGE_OR_SEARCH_HUB_NAME>

    • Origin 2 (tab/interface) is <TAB_OR_SEARCH_INTERFACE_NAME>

    • Language is <LANGUAGE>

    Where you replace:

  6. Click Add card to section, and then add a Metric card with the Search Event Count metric (see Add metric cards).

  7. Click Add card to section, and then add a Table card with the following dimension and metric (see Add table cards in usage analytics dashboards):

    • Dimensions: User Query

    • Metrics: Click Event Count

  8. Based on the Search Event Count value (obtained in the previous step) and the reference table at the beginning of the article, add the following metric filter: Click Event Count Is greater than or equal to <N>

    Where you replace <N> with the minimum number of clicks as found in the reference table.

    For example, if your search page has received 152 235 queries in English, you must add Click Event Count Is greater than or equal to 3 as the metric filter.

    Note

    If you already have a QS model, you can access the model information panel to see the exact minimum number of times that the query must be performed and followed by a click for a specific language (see Review model information).

  9. Save the dashboard.

  10. Browse the table card and see how many queries match Coveo ML QS criteria.

Note

Ensure that your Coveo search box doesn’t show an empty recommendation popup when no query suggestions are available.

When you’re done creating your dashboard, it should look like this:

report example

Review query suggestion candidates using the Usage Analytics Read API

The following JSON shows a configuration that you can use to create the above report using the Usage Analytics Read API (see Reports API - Version 15 - Create a report):

{
 "displayName": "<DASHBOARD_NAME>",
 "type": "DASHBOARD",
 "configuration": {
  "description": "<DESCRIPTION>",
  "dateRange": {
   "range": "days",
   "length": 91,
   "offset": -91
  },
  "compareRange": {
   "range": "days",
   "length": 91,
   "offset": -182
  },
  "tabs": [
   {
    "title": "<TAB_NAME>",
    "sections": [
     {
      "title": "",
      "position": {
       "sizex": "6",
       "sizey": "4",
       "col": "1",
       "row": "1"
      },
      "cards": [
       {
        "title": "<METRIC_CARD_TITLE>",
        "cardType": "QuickMetric",
        "eventType": "join",
        "href": "",
        "headerHref": "",
        "position": {
         "minSizex": 1,
         "minSizey": 1,
         "sizex": 1,
         "sizey": 1,
         "col": 1,
         "row": 1
        },
        "metric": "PerformSearch",
        "showTrend": false,
        "exceedsLicense": false,
        "valueType": "total",
        "filters": "",
        "bindOnLastSearch": true
       },
       {
        "title": "<TABLE_CARD_TITLE>",
        "cardType": "DetailedStatistics",
        "eventType": "join",
        "href": "",
        "headerHref": "",
        "position": {
         "minSizex": 1,
         "minSizey": 2,
         "sizex": 1,
         "sizey": 3,
         "col": 2,
         "row": 1
        },
        "filters": "",
        "metricFilters": "(DocumentView>=<MIN_VALUE>)",
        "bindOnLastSearch": true,
        "showCount": false,
        "showHeader": true,
        "sortBy": "DocumentView",
        "ascending": false,
        "dimensionsHeaders": {},
        "metricsHeaders": {},
        "metrics": [
         "DocumentView"
        ],
        "dimensions": [
         "queryExpression"
        ],
        "metricsSort": [
         "DocumentView"
        ],
        "dimensionsSort": [
         "queryExpression"
        ]
       }
      ],
      "editMode": true
     }
    ],
    "active": true,
    "editMode": false
   }
  ],
  "filters": "(queryexpression!='' AND queryexpression!=null) AND (originlevel1=='<ORIGIN_1_VALUE>') AND (originlevel2=='<ORIGIN_2_VALUE>') AND (language=='<LANGUAGE>')",
  "version": 6
 },
 "allAnalyticsViewer": true,
 "filters": [
  ""
 ]
}

Where you replace:

  • <DASHBOARD_NAME> with a title for the dashboard (for example, Queries Suggested by Coveo ML)

  • <DESCRIPTION> with a description for the dashboard

  • <TAB_NAME> with a name for the report tab on which the dashboard will be displayed

  • <METRIC_CARD_TITLE> with a name for the metric card that displays the total Search Event Count

  • <TABLE_CARD_TITLE> with a name for the table card that displays the queries that meet the requirements to be suggested by Coveo ML

  • <MIN_VALUE> with the minimum number of clicks a query must have to appear as a query candidate (as found in the reference table)

  • <ORIGIN_1_VALUE> with the value of the desired Origin 1 (Page/Hub) (formerly Search Hub)

  • <ORIGIN_2_VALUE> with the value of the desired Origin 2 (Tab) (Formerly Search Interface)

  • <LANGUAGE> with the desired ISO 639-1 language code (for example, en)

Pre-populating query suggestions

You can pre-populate or add queries to be suggested by a Coveo ML QS model by configuring a Default Queries file through the Advanced Model Configurations API.

This is useful in test environments to make sure that a QS model makes suggestions or to help a new model provide suggestions by including queries originating from an existing site.

Required privileges

The following table indicates the required privileges to view and edit dashboards from the Reports (platform-ca | platform-eu | platform-au) page and associated panels (see Manage privileges and Privilege reference).

Note

Access to dashboards or part of their content may be further restricted as a function of the member (see Manage access to reports and Manage permission filters).
Action Service - Domain Required access level
View reports

Analytics - Analytics data

Analytics - Reports

Organization - Organization

 View
Add, edit, and delete reports

Analytics - Analytics data

Organization - Organization

 View

Analytics - Reports

 Edit
Analytics - Administrate Allowed
1. The minimums are calculated, among other things, per language, therefore more popular languages will have a higher minimum number of times. You can review the minimum for each language in the model information panel (see Review model information).