Getting Query Suggestions

You can request basic query expression completions from a Coveo™ Machine Learning (Coveo ML) query suggestions model by sending a GET or POST HTTP request to https://platform.cloud.coveo.com/rest/search/v2/querySuggest (or https://cloudplatform.coveo.com/rest/search/querySuggest on Coveo Cloud V1).

The Search API query suggestions route supports several parameters which you can include either in the query string of a GET request, or in the JSON body of a POST request (see Query Suggest Parameters).

When using an OAuth2 token to authenticate a GET or POST HTTP request to the Search API query suggestions route, you must specify the unique identifier of the target Coveo Cloud organization by including the organizationId argument in the query string of your request.

  1. Requesting query suggestions using the GET method:

    GET https://platform.cloud.coveo.com/rest/search/v2/querySuggest?locale=en&q=twa&searchHub=BookstoreSearch HTTP/1.1
       
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    
  2. Requesting query suggestions using the POST method:

    POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
       
    Content-Type: application/json
    Accept: application/json
    Authorization: Bearer **********-****-****-****-************
    

    Payload

    {
      "locale": "en",
      "q": "twa",
      "searchHub": "BookstoreSearch"
    }
    

    200 OK response body (excerpt)

    {
      "completions": [
        {
          "executableConfidence": 1,
          "expression": "mark twain",
          "highlighted": "[mark] {twa}[in]",
          "score": 14.525258530973204
        },
        {
          "executableConfidence": 0.6666666666666666,
          "expression": "[wes]{twa}[rd] [ho]",
          "highlighted": "",
          "score": 8.50548085208594
        },
        {
          "executableConfidence": 0.5,
          "expression": "hot water music",
          "highlighted": "[hot] (wat)[er] [music]",
          "score": 7.107770631785241
        },
        ...
      ]
    }
    
  • If the query suggestions request is routed to a query pipeline with no associated Coveo ML query suggestions model, the request will return an empty completions array.

  • In a completions array item:

    • The score property value only has relative significance within the same completions array.

      For instance, a suggestion with a score of 14.811407079917723 in the completions array of response A is not necessarily less relevant than a suggestion with a score of 24.325728875625282 in the completions array of response B.

    • The highlighted property uses the following logic:
      • Characters between curly braces (e.g., {cat}) indicate an exact match with q.
      • Characters between square braces (e.g., [cher]) indicate completions.
      • Characters between parentheses (e.g., (act)) indicate corrections to q.
    • The executableConfidence property contains a floating-point value between 0 and 1 indicating how “convinced” Coveo ML is that performing a query with this suggestion as a basic query expression will return relevant results. The threshold from which Coveo ML considers a query suggestion executable is 0.8.

Query Suggestions Parameters

This section provides reference documentation for the available parameters when sending a GET or POST HTTP request to the Search API query suggestions endpoint.

actionsHistory (array)

The query and page view actions previously made by the current user.

Coveo Machine Learning event recommendations models use this information to provide contextually relevant output.

Note:

Page view actions are typically populated by the coveo.analytics.js script.

context (object)

The custom context information to send along with the request. Must be a dictionary of key-value pairs (JSON) where each key is a string, and each value is either a string or an array of strings.

Coveo Machine Learning models may use this information to provide contextually relevant output. Moreover, this information is accessible with the query pipeline language (QPL).

Note:

When logging a Search usage analytics event for a query, the customData field of that event should include the same data as the context parameter of the query. However, each context key included in customData must be prefixed by context_ (e.g., the userRoles key in context becomes context_userRoles in customData).

See also the referrer parameter.

Sample value: {"userAgeRange":"25-35","userRoles":["PremiumCustomer","ProductReviewer"]}

count (integer [int32])

The desired number of query suggestions.

debug (boolean)

Whether to force a successful response to include debug information.

Note:

Debug information can only appear in responses in the JSON format (see the format parameter).

Default value: false

enableWordCompletion (boolean)

Whether to attempt to complete the last word of the current basic query expression (see the q parameter) and boost the ranking score of the resulting expression so that it is returned as the first query suggestion.

format (string)

The format of a successful response.

  • Use json to get the response in the JSON format.
  • Use opensearch-atom or opensearch-rss to get the results in an OpenSearch format (XML).
  • Use xlsx to generate an Excel file containing the results (binary).

Note:

Debug information (see the debug parameter) can only appear in a response in the JSON format.

Default value: json

indexToken (string)

The Base64 encoded identifier of the index mirror to forward the request to.

If you do not specify an indexToken value, any index mirror could be used.

Note:

Passing an indexToken value has no effect when the results of a specific request can be returned from cache (see the maximumAge parameter).

Sample value: ZXhhbXBsZWluZGV4bWlycm9yLS4uLg==

indexType (string)

The type of index to query.

Allowed values are:

  • coveo
  • elasticsearch

Default value is coveo.

isGuestUser (boolean)

Whether the current user is anonymous.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note:

When logging a Search usage analytics event for a query, the anonymous field of that event should be set to the isGuestUser value of the query.

Default value is false.

locale (string)

The locale of the current user. Must comply with IETF’s BCP 47 definition.

Coveo Machine Learning models use this information to provide contextually relevant output. Moreover, this information is accessible with the query pipeline language (QPL).

Note:

When logging a Search usage analytics event, the language field of that event should match the language part of the locale value of the query (e.g., en-US in locale becomes en in language).

Sample value: en-US

maximumAge (integer [int32])

The maximum age of cached results, in milliseconds.

If the results of a specific request are available in the cache, and if those results are no older than the maximumAge value, the service returns those results rather than forwarding a new query to the index.

Default value is -1, which corresponds to the internal default value (15 minutes).

Note:

This parameter is automatically overridden when staticQuery is set to true.

Default value: -1

mlParameters (object)

A map of parameters to pass to the Coveo Machine Learning models for this request.

Available parameters:

  • num: The number of results to request. Value must be an integer between 1 and 50 inclusively. This parameter applies to all types of Coveo ML models (i.e., automatic relevance tuning, query suggestions, and event recommendations).

pipeline (string)

The name or ID of the query pipeline to use for this request (bypassing its conditions, if it has any).

You can pass an empty pipeline value to use an empty query pipeline (i.e., ?pipeline= or "pipeline": "").

If a query does not contain the pipeline parameter, the first query pipeline whose conditions are met by the request is used (query pipelines without conditions are not evaluated). Should the request fail to meet the conditions of each evaluated query pipeline, the default query pipeline of the target Coveo Cloud organization is used (bypassing its conditions, if it has any).

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific pipeline.
  • For reporting purposes, when logging a Search usage analytics event for a query, the queryPipeline field of that event should be set to the pipeline value of the query (or to the "default" string, if no pipeline value was specified in the query).

See also Managing Query Pipelines.

Sample value: CustomerQueryPipeline

q (string)

The basic query expression, typically the keywords entered by the end user in a query box.

Sample value:

Coveo "Cloud V2" platform

recommendation (string)

The identifier of the recommendation interface from which the request originates.

Coveo Machine Learning event recommendations models may use this information to provide contextually relevant output.

Sample value: RecommendedProducts

referrer (string)

The third level of origin of the request, typically the URL of the page that linked to the search interface from which the request originates (e.g., in JavaScript, this would correspond to the document.referrer value).

Coveo Machine Learning models may use this information to provide contextually relevant output.

Note:

When logging a Search usage analytics event for a query, the originLevel3 field of that event should be set to the referrer value of the query, if specified.

See also the context parameter.

Sample value: http://www.example.com/

searchHub (string)

The first level of origin of the request, typically the identifier of the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Notes:

  • This parameter will be overridden if the search request is authenticated by a search token that enforces a specific searchHub.
  • When logging a Search usage analytics event for a query, the originLevel1 field of that event should be set to the value of the searchHub search request parameter.

See also the tab parameter.

Sample value: CustomerPortal

tab (string)

The second level of origin of the request, typically the identifier of the selected tab in the graphical search interface from which the request originates.

Coveo Machine Learning models use this information to provide contextually relevant output.

Note:

When logging a Search usage analytics event for a query, the originLevel2 field of that event should be set to the tab value of the query (or to the "default" string, if no tab value was specified in the query).

See also the searchHub parameter.

Sample value: ForumTab

timezone (string)

The tz database identifier of the time zone to use to correctly interpret dates in the query expression and result items.

If not specified, the default time zone of the server hosting the index is used.

Note:

While no Coveo Machine Learning model uses this information, it can nevertheless affect the ranking scores (and thus, potentially the order) of result items, as ranking expressions may be based on time constants.

Sample value: America/New_York

visitorId (string)

A GUID representing the current user, who can be authenticated or anonymous. This GUID is normally generated by the usage analytics service and stored in a non-expiring browser cookie.

Coveo Machine Learning models may use this information to provide contextually relevant output.

Troubleshooting

If your query suggestions model is not behaving as expected, this may be due to a mismatch between the searchHub value used in your Search API requests and the originLevel1 value used when logging events for the target search interface through the Usage Analytics Write API. It is important that those values match in any given search interface, since the Coveo ML service uses them as filter fields.

You have a search interface for books, and another one for movies.

On the usage analytics side, when logging events in those search interfaces, the originLevel1 value specified in your requests is, respectively, BookstoreSearch and MovieStoreSearch (see Logging Search Events).

On the Search API side, this translates into very distinctive behavior from one searchHub to another. You make the following request:

POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
   
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "Dost",
  "searchHub": "BookstoreSearch"
}

The Search API returns the following completions, where the Dostoevsky suggestion is executable and highly recommended:

200 OK response body (excerpt)

{
  "completions": [
    {
      "executableConfidence": 1,
      "expression": "Dostoevsky",
      "highlighted": "{Dost}[oevsky]",
      "score": 56.135864235791246
    },
    ...
  ]
}

You make the following request to the Search API:

POST https://platform.cloud.coveo.com/rest/search/v2/querySuggest HTTP/1.1
   
Content-Type: application/json
Accept: application/json
Authorization: Bearer **********-****-****-****-************

Payload

{
  "q": "Dost",
  "searchHub": "MovieStoreSearch"
}

The Search API returns the following completions, where Dosti (a highly successful Hindi film) is executable and highly recommended, and where Dostoevsky does not figure at all:

200 OK response body (excerpt)

{
  "completions": [
    ...
    {
      "executableConfidence": 1,
      "expression": "Dosti",
      "highlighted": "{Dost}[i]",
      "score": 35.183255413846215
    },
    ...
  ]
}

Hence, when in the BookstoreSearch search interface, it is very important to pass the "searchHub": "BookstoreSearch" for the relevant query suggestion Dostovesky to be returned, instead of Hindi films.

Analogous remarks hold for the tab value used in your Search API requests and the originLevel2 value used in your Usage Analytics Write requests.