Custom context
Custom context
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:
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:
-
If the end-user action triggers a query or query suggestion request:
-
The request is routed to a specific query pipeline (see About the query pipeline routing algorithm).
NoteThe context may be used to evaluate query pipeline conditions.
-
Apply each statement whose condition is satisfied in that pipeline.
-
If Coveo ML models are configured in the query pipeline, the models may use the context to affect the request accordingly.
-
Return the results to the user interface, and render those results for the end user to see.
-
-
If the search interface is configured to log usage analytics events, log the corresponding event, with its context, using the Usage Analytics Write API.
Note
Members using the {model-testing-link} page can use this context with the Coveo Administration Console to generate reports that contain specific contextual information. 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’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 |
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_
-prefixedcustomData
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 |
Related articles
Product | Resources |
---|---|
Coveo for Salesforce | |
Coveo for Sitecore | |
Coveo JavaScript Search Framework |