Custom context

This is for:

Developer System Administrator

Your search interface can send custom contextual information (for example, user role, country, age range, etc.) along with each query it executes and each Coveo Usage Analytics (Coveo UA) event it logs. 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 data to provide more personalized and relevant search results, query completion, facet reordering, or content recommendations.

Note

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 (that is, 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
Note

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 About the query pipeline routing algorithm).

      Note

      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.

    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.

Additional information

Typically, in a JavaScript Search Framework search interface, you’ll 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. 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).

Note

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’s 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; for example, $qre(expression: @audience==$context.userRole, modifier: 100))

  • Query pipeline conditions (using the $context QPL object; for example, $context[userRole] is "administrator")

Note

When referencing a value from the $context QPL object in a query expression, use dot notation (for example, $context.userRole); otherwise, use square brackets notation (for example, $context[userRole]). In a QPL statement/query pipeline condition, this means that whenever you reference a $context value in an expression that isn’t between back-ticks (`), you must use square brackets notation.
Product Resources
Coveo for Salesforce
Coveo for Sitecore
Coveo JavaScript Search Framework