---
title: Custom context
slug: '2081'
canonical_url: https://docs.coveo.com/en/2081/
collection: leverage-machine-learning
source_format: adoc
---
# Custom context
Your [search interface](https://docs.coveo.com/en/2741/) can send custom contextual information (for example, user role, country, age range, etc.) along with each [query](https://docs.coveo.com/en/231/) it executes and each [Coveo Analytics event](https://docs.coveo.com/en/260/) it logs.
This data can then be leveraged in query expressions, [query pipeline](https://docs.coveo.com/en/180/) [statements](https://docs.coveo.com/en/236/) and [query pipeline conditions](https://docs.coveo.com/en/2793/), and as user defined [dimensions](https://docs.coveo.com/en/258/) in Coveo Analytics [reports](https://docs.coveo.com/en/266/).
[Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [models](https://docs.coveo.com/en/1012/) can also exploit [custom data](https://docs.coveo.com/en/1341/) to provide more personalized and relevant search results, query completion, [facet](https://docs.coveo.com/en/198/) reordering, or content recommendations.

> **Note**
>
> If you intend a custom [context](https://docs.coveo.com/en/1345/) 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](https://docs.coveo.com/en/assets/images/passing-query-and-pipeline-context.svg)

> **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](https://docs.coveo.com/en/1507/)).

> **Note**
>
> The 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](https://docs.coveo.com/en/3389/).
 .. 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 Coveo Analytics events, log the corresponding event, with its context, using the Usage Analytics Write API.

## Additional Information

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

* User-defined Coveo Analytics dimensions

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

* Query expressions (using the `$context` [query pipeline language (QPL)](https://docs.coveo.com/en/235/) 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.

## Related articles

To leverage custom context, depending on the library you're using, see the following.

[cols="1,2"]
|===
|Product |Resources

| [Coveo for Salesforce](https://docs.coveo.com/en/1243/)
a|

* [Leverage custom context attributes in the query pipeline](https://docs.coveo.com/en/3389#leverage-custom-context)
* [Send context information in Salesforce Lightning](https://docs.coveo.com/en/3290/)
* [Send Apex context to a JavaScript Search interface](https://docs.coveo.com/en/1169/)

| [Coveo for Sitecore](https://docs.coveo.com/en/557/)
a|

* [Coveo for Hive UI Framework - Context Component Properties](https://docs.coveo.com/en/952/)
* [Coveo for Hive UI Framework - Bind with User Context component properties](https://docs.coveo.com/en/923/)
* [Get started with Coveo Machine Learning in Sitecore](https://docs.coveo.com/en/572/)

| [Coveo Atomic Library](https://docs.coveo.com/en/atomic/latest)
a| [Leverage custom context](https://docs.coveo.com/en/3389#leverage-custom-context)

| [Coveo Headless Library](https://docs.coveo.com/en/headless/latest)
a| [Sending context with Headless](https://docs.coveo.com/en/3389#sending-context-with-headless)

| [Coveo JavaScript Search Framework](https://docs.coveo.com/en/375/)
a| [Send custom context information](https://docs.coveo.com/en/399/)
|===