Understanding Custom Context

Your search interface can send custom contextual information (e.g., user role, country, age range, etc.) along with each query it executes and each Coveo Usage Analytics (Coveo UA) event it logs (see Sending Custom Context Information). This data can then be leveraged in query expressions, query pipeline statements and query pipeline conditions, and as user defined dimensions in usage analytics reports. Coveo™ Machine Learning (Coveo ML) models can also exploit custom contextual data to provide more personalized and relevant search results, query completion, facet reordering, or content recommendations.

If you intend a custom context to be usable by Coveo ML, you should ensure that its possible values are limited to a low-cardinality range (i.e., maximum of 10 possible values).

The following diagram shows the process of a query or query suggestion request being sent from a search interface and how the custom context is handled:

Passing Query and Pipeline Context diagram

The diagram focuses on actions in a search interface that trigger queries or query suggestion requests. Other actions can be triggered from a search interface that do not use the Search API.

When an end user interacts with a search interface that has been configured to leverage custom contextual information when an action is performed:

  1. If the end-user action triggers a query or query suggestion request:

    1. The request is routed to a specific query pipeline (see Understanding the Query Pipeline Routing Algorithm).

      The context may be used to evaluate query pipeline conditions.

    2. Apply each statement whose condition is satisfied in that pipeline.

    3. If Coveo ML models are configured in the query pipeline, the models may use the context to affect the request accordingly (see Leveraging Custom Contexts in Coveo Machine Learning Features).

    4. Return the results to the user interface, and render those results for the end user to see.

  2. If the search interface is configured to log usage analytics events, log the corresponding event, with its context, using the Usage Analytics Write API.

    Members of the Administrators, Analytics Managers, and Relevance Managers built-in groups can use this context with the Coveo Cloud administration console to generate reports that contain specific contextual information (see Creating Usage Analytics Dashboards). Furthermore, the ML models process usage analytics data to continuously improve the relevancy of their output.

Additional Information

Typically, in a JavaScript Search Framework search interface, you will use the PipelineContext component to determine the custom context information you want to send along with each query, and likely along with each UA event as well (see Sending Custom Context Information). Furthermore, if an Analytics component is active in the search interface as well, the specified custom context information is also added to the customData property of each logged usage analytics event (UA Write API).

In a search interface that relies on the JavaScript Search Framework, custom context keys logged in the customData UA event metadata are automatically prefixed by context_ so that the Coveo ML service knows it should learn from those custom context key-values.

It is also important to keep in mind that custom context information can be exploited through:

  • User defined UA dimensions

  • Coveo ML (models can learn from context_-prefixed customData key-values in past UA events to promote content that matches the context key-values of the current query)

  • Query expressions (using the $context query pipeline language (QPL) object; e.g., $qre(expression: @audience==$context.userRole, modifier: 100))

  • Query pipeline conditions (using the $context QPL object; e.g., $context[userRole] is ”administrator”)

When referencing a value from the $context QPL object in a query expression, use dot notation (e.g., $context.userRole); otherwise, use square brackets notation (e.g., $context[userRole]). In a QPL statement/query pipeline condition, this means that whenever you reference a $context value in an expression that is not between back-ticks (`), you must use square brackets notation.