Adding Machine Learning Query Suggestions Models

Coveo™ Machine Learning (Coveo ML) is a service that leverages usage analytics data (see Coveo Machine Learning). Query Suggestions is a Coveo ML feature that optimizes query completion suggestions that can be proposed to users as they type queries in a search box (see Query Suggestions Feature).

You configure a Query Suggestions model from the Coveo Cloud administration console for a query pipeline defined in your Coveo Organization. You add a machine learning model built from a usage analytics data set recorded over a given period, and set the frequency at which the model is retrained to maintain its freshness (see Coveo Machine Learning Models). The default values for available parameters are typically appropriate for in most cases, but the following procedure details why or when you may want to change them.

For a Salesforce community search page, you create a model that looks at the last 3 months of usage analytics data and schedule to retrain the model every week to keep it fresh.

A Coveo ML Query Suggestions model automatically includes sub-models for search hubs, interfaces, and languages to ensure the query suggestions are relevant to the context. This means that you do not need to create separate models for each tab, interface, or language.

A user typing a query in English in the Knowledge Articles interface (tab) of the Community hub gets search box query completion suggestions optimized for this context combination. The suggestions may be different if the same query is typed in another interface, or obviously in another language on the same hub. If you also have an internal Agents hub, this means that the agent queries cannot affect the Community hub suggestions and vice versa.

Add a Query Suggestions Model

  1. If not already done, log in to your Coveo Organization with an Admin or Relevance Analyst user role account.

  2. Ensure that your Coveo Organization collects usage analytics data for the search hub on which you want to activate Query Suggestions (see Coveo Cloud Usage Analytics).

    Query Suggestions predictive models are based on Coveo Cloud usage analytics data. If no usage analytics data is available, there will be no recommendations, but recommendations will improve as more data becomes available each time the model is retrained (see Training and Retraining).

  3. Before creating a model, review queries that match Query Suggestions criteria (see Reviewing Suggested Queries by Coveo Machine Learning).

  4. When relevant queries are missing, add those queries among suggestions by manually generating usage analytics events:

    You can also create a tool or a script to generate events. The queries must be sent with 10 different visit IDs.

    1. In the browser of your choice, in private mode, access your Coveo Cloud search interface.

    2. Without being authenticated, perform a query that you wish to be suggested.

    3. Click a result title.

    4. Close your browser.

    5. Repeat this procedure ten times for each query.

      It may take up to 15 minutes before suggestions become available to a Coveo ML model.

  5. In the navigation bar on the left, under Search Optimization, select Query Pipelines.

  6. In the Query Pipelines page, in the Name column, click the query pipeline for which you want to manage Query Suggestions, typically the one used by the search interface for which you want to activate Coveo ML Query Suggestions.

  7. In the Machine Learning tab:

    If the Machine Learning tab is not visible, contact Coveo Support to request to enable Coveo ML in your Coveo Cloud organization.

    • Create a Query Suggestions model by clicking Add Model.

      Because a Query Suggestions model automatically includes sub-models for hubs, interfaces, and languages, you typically need only one Query Suggestions model in your query pipeline.

      However, you need to create separate models only when you have cases where any of the model parameters described below must have a different value in each case.

      Your customers perform around 30,000 queries per day on your Community search hub while your small team of support agents perform only around 500 queries per day on your Agent search hub. Because significantly less usage analytics data is available from the agent hub, you may want to base the model on 6 months of data for the Agent search hub and only 3 months of data for the Community search hub.

      OR

    • (For developers only) Create a Query Suggestions model in Query Pipeline Language (QPL):

      You can directly enter a configuration rule that respects the Query Pipeline Language (QPL) syntax for a Query Suggestions model.

      1. Click Add Model with Code.

      2. In the form editor box that appears, enter a Query Suggestions (querySuggest) model configuration rule (see REST Search API Models).

      3. Click Save.

      OR

    • Modify an existing model by clicking the model to change or, clicking the Actions icon (Icon-SourceActions) and then selecting Edit model.

      Currently, when you edit an existing model, the query suggestions service is interrupted for about one hour while the model is trained with the new configuration. The recommended work around is to rather duplicate and customize the model, and make the new model effective when it is ready (see Editing a Coveo Machine Learning Model Without Service Interruption).

  8. In the Add a Machine Learning Model or Edit a Machine Learning Model panel, in the left section:

    1. (In the Add a Machine Learning Model panel only) Click the Select model type drop-down menu, and then select Suggest queries.

    2. In the User note input, enter useful information such as the creation or edition date and the purpose of the model.

      John Smith - 2016-09-17 - Improve the queries suggested to our online help users

  9. In the Add a Machine Learning Model or Edit a Machine Learning Model panel, in the right section, evaluate if you need to change some of the default values:

    1. In the Training set section:

      1. In the Update frequency drop-down menu, select the time interval at which the model is retrained between the following values: Daily, Weekly, or Monthly. The default value is Weekly for the default 3 months Data period (see Training and Retraining).

      2. In the Data period drop-down menu, select the usage analytics data time interval on which the model will be based. Available data periods depend on the Update frequency you select (see Training and Retraining). The default value is 3 months, meaning the last 90 days from today.

        As a general guide, the Data period should include a minimum of 10,000 queries. When you have different hubs, interfaces, and languages, a higher number of queries would be better so that each sub-model has access to a significant data set.

        Consider selecting a longer period when your search interface serves a small number of queries to improve the suggestions relevancy by using a larger data set.

        Consider selecting a shorter period when your search interface serves a large number of queries and you want the suggestions to be more responsive to user behavior trends.

      3. When you want or need to refine the data that the model will use to learn and return suggestions, consider adding a hub filter:

        If you need to create more than one query suggestions model in your query pipeline, you should add a data filter to feed only the data appropriate to each pipeline.

        1. Under Train on events, select the Specific radio button.

        2. Click Origin 1 (Page/Interface).

        3. Select the Is operator.

        4. In the Enter filter value input, select or type the name for your search hub.

        5. Click Add Filter.

      4. When you want to train the Query Suggestions model with usage analytics data from a specific geographic origin, consider creating Country and or Region filters.

    2. In the Condition to be applied section, apply a condition on the model:

      If you added one or more data filters in a previous step, you generally want to duplicate your data filter condition as a model condition so that the recommendations are returned only when this condition is met.

      In the list of available conditions, select a condition.

      • When there are many conditions, in the filter box, type a word from the condition you are looking for to refine the list of displayed conditions.

      • Below the condition list, select 10 or 100 to set the number of conditions per page. By default, the table shows 10 conditions per page. You can also click the left and right arrow icons, or a page number to navigate through condition pages.

      OR

      Create a new condition by clicking Add Condition (see Create a Condition).

      OR

      Edit an existing condition:

      1. Click Manage Conditions.

        You lose all unsaved changes if you clicked Confirm in the Are You Sure confirmation prompt that appears. It is thus recommended to Save the model before creating a condition.

      2. In the Conditions page, edit a condition (see Modify a Condition).

      3. Access again the Condition to be applied section of a new model or the model you edited.

      4. In the list of available conditions, select the condition you edited.

        • When there are many conditions, in the filter box, type a word from the condition you are looking for to refine the list of displayed conditions.

        • Below the condition list, select 10 or 100 to set the number of conditions per page. By default, the table shows 10 conditions per page. You can also click the left and right arrow icons, or a page number to navigate through condition pages.

  10. At the bottom of the Add a Machine Learning Model or Edit a Machine Learning Model panel, click Add or Save.

    The instructions to create or modify the model are sent to the Coveo ML service.

  11. When you edit a model, in the Are You Sure? dialog box, click Confirm only when it is acceptable for you to get a query suggestions service interruption, which is very noticeable for end-users that are expecting suggestions to appear below the search box.

    Otherwise, click Cancel and use the other method (see Editing a Coveo Machine Learning Model Without Service Interruption).

    CCV2AC_ARTAreYouSure2

  12. Back in the Machine Learning tab of your pipeline page, on the model row, in the Status column, the value is most probably Creating.

    The value will change to Active when the model creation or modification is completed, typically within 30 minutes, depending on the amount of usage analytics data to process. Query Suggestions can return recommendations only when the model has a Active status.

  13. Validate that Coveo ML Query Suggestions are operational, using the following Coveo Platform API call:

    https://cloudplatform.coveo.com/rest/search/querySuggest?query={keyword}&access_token=mytoken

    where you replace:

    • keyword by a frequent query for your search hub.

    • mytoken by a valid search token for your search hub.

    The recommended query suggestions should appear in JSON format.

    You replace keyword by install and get:

    {
    "completions": [
        {
        "value": "install",
        "score": 1007.5376999820605,
        "highlighted": "(instal)[l]",
        "confidence": 0.75
        },
        {
        "value": "install coveo for sitecore",
        "score": 10.050266642747307,
        "highlighted": "(instal)[l] [coveo] [for] [sitecore]",
        "confidence": 0.1
        },
        {
        "value": "installation",
        "score": 9.633365796878904,
        "highlighted": "(instal)[lation]",
        "confidence": 0.1
        },
        {
        "value": "install ces",
        "score": 9.203820017092077,
        "highlighted": "(instal)[l] [ces]",
        "confidence": 0.125
        },
        {
        "value": "initsearchbox",
        "score": 7.193725823503939,
        "highlighted": "(initsearchbox)",
        "confidence": 0.1
        }
    ]
    }
    
  14. Coveo for Salesforce 2.26 - July 2016  Enable Query Suggestions in the search box of your search hub.

    Reveal-QuerySuggestionsEx3

    In a JavaScript Search Framework search box, the Coveo ML query suggestions can be made available through the Coveo Component Omnibox.

    Using the Interface Editor (see Accessing the Coveo Interface Editor):

    1. Hover over the search box, and then click the Edit icon (Icon-Edit2) (see Customize a User Interface Component).

    2. In the Searchbox Options component configuration panel, ensure that Enable Omnibox and Enable Reveal query suggestions addon are activated.

    3. It is also recommended to activate Show Omnibox result inline and Enable search-as-you-type (at the top of the panel) to maximize the Coveo ML experience.

      Show Omnibox result inline pushes down the search interface elements below the search box when the Omnibox appears rather than appearing above them.

      Enable search-as-you-type when Enable Reveal query suggestions addon is activated performs a query with the first Coveo ML suggestion when it changes as the user types in the search box. Because the search-as-you-type queries are made with full Coveo ML suggested keyword(s) rather than often incomplete keywords, the returned results are significantly more relevant.

      • Behind the scenes, the Interface Editor modifies your search page HTML markup for the Searchbox component by enabling:

        • the Omnibox

        • the Coveo ML query suggest addon

        • (optional) if the Omnibox pushes down (inline) or appears above the search results

        • (optional) the search-as-you-type option

          <div id="search" class="CoveoSearchInterface">
          ...
          <div class="CoveoSearchbox"
              data-enable-omnibox="true"
              data-enable-reveal-query-suggest-addon="true"
              data-inline="true"
              data-enable-search-as-you-type="true">
          </div>
          ...
          <div class="CoveoAnalytics"></div>
          ...
          </div>
        

        The Analytics component (div with CoveoAnalytics class) should also already be there to instruct the search interface to push search events to the usage analytics.

      • When data-enable-search-as-you-type="true", the JavaScript Search includes enableWordCompletion="true" in its request, in which case, as the first suggestion, the Query Suggestions returns the best match to complete the currently typed keyword.

        The current keyword completion has a significantly higher score than the other suggestions.

        In the Query Suggestion JSON response returned after typing dow in the search box, the first suggestion (download) has a score above 1000, while the other ones are below 17.

          {
          "completions" : [ {
              "expression" : "download",
              "score" : 1016.6772794999547,
              "highlighted" : "{dow}[nload]",
              "executableConfidence" : 1.0
          }, {
              "expression" : "set point download",
              "score" : 16.677279499954697,
              "highlighted" : "[set] [point] {dow}[nload]",
              "executableConfidence" : 1.0
          }, {
              "expression" : "unifying software download",
              "score" : 16.39136503539789,
              "highlighted" : "[unifying] [software] {dow}[nload]",
              "executableConfidence" : 1.0
          }, {
              "expression" : "setpoint download",
              "score" : 16.226351404582463,
              "highlighted" : "[setpoint] {dow}[nload]",
              "executableConfidence" : 1.0
          }, {
              "expression" : "m570 downloads",
              "score" : 15.611453176387084,
              "highlighted" : "[m570] {dow}[nloads]",
              "executableConfidence" : 1.0
          } ]
          }
        

Who Can Perform the Page Actions

The required roles are:

  • Administrator

    OR

  • Relevance Analyst