Associate a Model via Query Pipeline Statements

This is for:

Developer System Administrator

You can configure Coveo Machine Learning (Coveo ML) models by creating query pipeline statements expressing the facetSense, querySuggest, recommendations, or topClicks features (see Query pipeline features).

Coveo ML models can enhance the end-user experience by:

  • Providing query suggestions that have yielded relevant results in the past (querySuggest, or Query Suggestions (QS) models).

  • Recommending related content based on the end-user’s recent actions, as well as on actions previously performed by similar end users (recommendations, or content recommendations models).

  • Ensuring that contextually relevant items appear in the query result list with an elevated ranking score, even if those items don’t match the basic and/or advanced query expression (topClicks, or Automatic Relevance Tuning (ART) models).

  • Reordering facets and facet values, and providing category-based item ranking score boosts (facetSense, or dynamic navigation experience models).

In the Coveo Administration Console, you can manage statements expressing Coveo ML features from the Machine Learning tab in a query pipeline configuration page.

See Manage models.

Dynamic navigation experience (facetSense, or DNE) models can’t currently be managed as query pipeline statements from the Administration Console. However, you can manage DNE models and model associations from the Administration Console (see Create a Dynamic Navigation Experience Model and Associate a model with a query pipeline).

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Apply Coveo ML models

Only query pipeline statements expressing the queryParamOverride feature may affect a QS request (that is, a GET or POST request to the /rest/search/v2/querySuggest route) before the querySuggest feature applies.

Syntax

Use the following query pipeline language (QPL) syntax to define a statement expressing the topClicks, querySuggest, recommendation, or facetSense features:

topClicks | querySuggest | recommendation | facetSense <modelConfiguration>

<modelConfiguration>

A comma-separated list of key-value pairs, where each key-value must be a valid QPL Coveo ML model configuration option.

QPL Coveo ML Model Configuration Options

The following table details the available configuration options when creating a Coveo ML model through QPL.

Option Type Applicable models Default Search API value Description
enabled Boolean All true Whether to enable the model.
commonFilter String All "" The filter to apply to common event dimensions when exporting usage analytics data to build the model.
searchEventFilter String All "" The filter to apply to search event dimensions when exporting usage analytics data to build the model.
customEventFilter String All "" The filter to apply to custom event dimensions when exporting usage analytics data to build the model.
exportPeriod String All "P1W" The length of time to consider when exporting usage analytics data to build/rebuild the model. Must be in the ISO-8601 format.
exportOffset String All "P0D" The offset period to apply when exporting usage analytics data to build/rebuild the model. Must be in the ISO-8601 format.
refreshRate String All "P1W" The frequency at which to rebuild the model. Must be in the ISO-8601 format.
cacheMaximumAge String All "PT1800s" The maximum age of cached query results items to consider. Must be in the ISO-8601 format.
displayName String All None A descriptive human-readable display name for the model.
maxResults Unsigned integer All except facetSense See description The maximum number of recommendations the model can output. Default Search API value is 10 for querySuggest and 5 for topClicks. For recommendations, the numberOfResults parameter of the search request is used by default.
modifier Integer All except querySuggest 50 (facetSense) or 1000 (recommendation/topClicks) The ranking score modifier to apply to items recommended by the model. Must be in range [-1000000, 1000000].
matchQuery Boolean topClicks only false Whether items recommended by the model must match the basic query expression.
matchAdvancedQuery Boolean topClicks only true Whether items recommended by the model must match the advanced query expression.
useRefinedQuery Boolean topClicks only false Whether to enable the intelligent term detection (ITD) feature on the model.