--- title: Reviewing query suggestion candidates slug: '2010' canonical_url: https://docs.coveo.com/en/2010/ collection: leverage-machine-learning source_format: adoc --- # Reviewing query suggestion candidates [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Query Suggestion (QS)](https://docs.coveo.com/en/1015/) [models](https://docs.coveo.com/en/1012/) suggest the most relevant [queries](https://docs.coveo.com/en/231/) that were previously performed by other users. To learn more about this model type, see [About Query Suggestions](https://docs.coveo.com/en/3386/). 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 [Query Suggestion (QS)](https://docs.coveo.com/en/1015/) [model](https://docs.coveo.com/en/1012/) 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](https://docs.coveo.com/en/l3od9093#default-queries) 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](https://docs.coveo.com/en/1337/)), search interface ([origin level 2](https://docs.coveo.com/en/1338/)), and language in the model. The query count is relative to the [model data period](https://docs.coveo.com/en/3398#learning-interval-section) (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. |=== | [[ReferenceTable]]Query count | Minimum number of times a given query must be performed and followed by a click (The minimums are calculated based on several factors, including 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)(https://docs.coveo.com/en/1894#qs-languages-section)).] | 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 Analytics](https://docs.coveo.com/en/182/) from a given search interface would be candidates for query suggestions, thereby 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](https://docs.coveo.com/en/183/) 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 to the [**Models**](https://platform.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/ai-and-ml/models/)) page of the Coveo Administration Console, and looking at the [**Information** section](https://docs.coveo.com/en/1894#query-suggestions-qs) of your specific model. This section contains a procedure that shows how to create a [dashboard](https://docs.coveo.com/en/256/) that displays the queries that meet the requirements to be suggested by a Coveo ML QS model for a specific search interface. These are queries that were performed and followed by a click the [required number of times](#ReferenceTable). The following procedure assumes that you're familiar with global dimension filters and dashboards (see [Add global dimension filters](https://docs.coveo.com/en/1675/) and [Review and manage dashboards](https://docs.coveo.com/en/1542/)). You could also build a dashboard using a JSON configuration. To create the dashboard using the [Usage Analytics Read API](https://docs.coveo.com/en/2671/), see [Review query suggestion candidates using the Usage Analytics Read API](#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**](https://docs.coveo.com/en/2948#search-event-cause) has the [`omniboxAnalytics`](https://docs.coveo.com/en/2948#omniboxanalytics-performsearch-manual) value. . On the [**Reports**](https://platform.cloud.coveo.com/admin/#/orgid/usage/reports/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/reports/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/reports/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/reports/)) page, click **Add**, and then select **Blank dashboard**. . 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`). . (Optional) Enter a dashboard description. . Select a date interval of three months (see [Set the period to review data](https://docs.coveo.com/en/1704/)). . Add the following global filters (see [Add global dimension filters](https://docs.coveo.com/en/1675/)): ** `User Query is not blank or n/a` ** `Origin 1 (page/hub) is ` ** `Origin 2 (tab/interface) is ` ** `Language is ` Where you replace: ** `` with the value of the desired [Origin 1 (Page/Hub) (formerly Search Hub)](https://docs.coveo.com/en/2948#origin-1-pagehub-formerly-search-hub) ** `` with the value of the desired [Origin 2 (Tab) (Formerly Search Interface)](https://docs.coveo.com/en/2948#origin-2-tab-formerly-search-interface) ** `` with the desired [ISO 639-1](http://en.wikipedia.org/wiki/ISO_639-1) language code (for example, `en`) . Click **Add card to section**, and then add a **Metric** card with the **Search Event Count** [metric](https://docs.coveo.com/en/263/) (see [Add metric cards](https://docs.coveo.com/en/2040/)). . Click **Add card to section**, and then add a **Table** card with the following dimension and metric (see [Add table cards](https://docs.coveo.com/en/1540/)): ** **Dimensions**: `User Query` ** **Metrics**: `Click Event Count` . Based on the **Search Event Count** value (obtained in a previous step) and the [reference table](#ReferenceTable) at the beginning of the article, add the following metric filter: `Click Event Count Is greater than or equal to ` Where you replace `` with the minimum number of clicks as found in the [reference table](#ReferenceTable). 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](https://docs.coveo.com/en/1894#qs-languages-section)). . Save the dashboard. . 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](https://docs.coveo.com/en/assets/images/leverage-machine-learning/queries-suggested-by-ml.png) ### 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](#review-query-suggestion-candidates) using the [Usage Analytics Read API](https://docs.coveo.com/en/2671/) (see [Reports API - Version 15 - Create a report](https://platform.cloud.coveo.com/docs?urls.primaryName=Usage%20Analytics%20Read#/Reports%20API%20-%20Version%2015/post%5F%5Fv15_reports)): ```json { "displayName": "", "type": "DASHBOARD", "configuration": { "description": "", "dateRange": { "range": "days", "length": 91, "offset": -91 }, "compareRange": { "range": "days", "length": 91, "offset": -182 }, "tabs": [ { "title": "", "sections": [ { "title": "", "position": { "sizex": "6", "sizey": "4", "col": "1", "row": "1" }, "cards": [ { "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": "", "cardType": "DetailedStatistics", "eventType": "join", "href": "", "headerHref": "", "position": { "minSizex": 1, "minSizey": 2, "sizex": 1, "sizey": 3, "col": 2, "row": 1 }, "filters": "", "metricFilters": "(DocumentView>=)", "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=='') AND (originlevel2=='') AND (language=='')", "version": 6 }, "allAnalyticsViewer": true, "filters": [ "" ] } ``` Where you replace: * `` with a title for the dashboard (for example, `Queries Suggested by Coveo ML`) * `` with a description for the dashboard * `` with a name for the report tab on which the dashboard will be displayed * `` with a name for the metric card that displays the total **Search Event Count** * `` with a name for the table card that displays the queries that meet the requirements to be suggested by Coveo ML * `` with the minimum number of clicks a query must have to appear as a query candidate (as found in the [reference table](#ReferenceTable)) * `` with the value of the desired [Origin 1 (Page/Hub) (formerly Search Hub)](https://docs.coveo.com/en/2948#origin-1-pagehub-formerly-search-hub) * `` with the value of the desired [Origin 2 (Tab) (Formerly Search Interface)](https://docs.coveo.com/en/2948#origin-2-tab-formerly-search-interface) * `` with the desired [ISO 639-1](http://en.wikipedia.org/wiki/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**](https://docs.coveo.com/en/l3od9093#default-queries) file through the [Advanced Model Configurations API](https://docs.coveo.com/en/l3od9093#default-queries). 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**](https://platform.cloud.coveo.com/admin/#/orgid/usage/reports/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/usage/reports/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/usage/reports/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/usage/reports/)) page and associated panels (see [Manage privileges](https://docs.coveo.com/en/3151/) and [Privilege reference](https://docs.coveo.com/en/1707/)). > **Note** > > Access to dashboards or part of their content may be further restricted as a function of the member (see [Manage access to reports](https://docs.coveo.com/en/1888/) and [Manage permission filters](https://docs.coveo.com/en/1917/)). [cols="~,~,~", options="header"] |=== .^|Action .^|Service - Domain .^|Required access level .3+|View reports |Analytics - Analytics data |View |Analytics - Reports |View |Organization - Organization |View .4+|Add, edit, and delete reports |Analytics - Analytics data |View |Organization - Organization |View |Analytics - Reports |Edit |Analytics - Administrate |Allowed |===