About custom context

This is for:

In this article

How contexts and Coveo Machine Learning models work
Leading practices
Leverage custom context
Sending context with Headless

Coveo Machine Learning (Coveo ML) models learn from user behavior to automatically improve Coveo-powered content relevance (see Leverage machine learning).

You can take the relevance of Coveo ML models one step further by defining and using custom contexts that are appropriate to your business.

Coveo ML models favor (or boost the ranking score of) content that matches or is accessed more often in the specified custom context. Because Coveo ML models don’t filter content based on this custom context, they can still provide output when there are few or no context matches.

Consider specifying a custom context for Coveo ML models when most queries should return different results depending on the context.

EXAMPLE

A user is already authenticated on your product documentation site. From their profiles, you can get their roles relative to your products (for example, end-user, administrator, or developer). This means that user role could be a good custom context.

Often, for similar queries (for example, entering only a feature name), users with different roles have different intentions and are looking for different kinds of information:

Developers - how to customize the product with code samples.
Administrators - look for installation and configuration articles.
End users - instructions on how to use the product.

With the user role as a custom context, Coveo ML models can promote content that’s more relevant to each user’s context.

Note

You can also use custom contexts in query pipeline conditions, and then apply these conditions to query pipeline elements.

How contexts and Coveo Machine Learning models work

In practice, custom contexts are key/value pairs that must be sent as custom data with standard or custom Coveo Usage Analytics (Coveo UA) events to build a contextualized activity history.

Note

With the new Event API, you wouldn’t send custom context when logging UA events, but the Search API would log any custom context passed in your search requests.

When a user makes a query and a context is specified, the matching relevant results with the highest activity history in this context are promoted. More technically, Coveo ML models use context like an intelligent query ranking expression (QRE), boosting results that match the query and the context. Coveo ML models automatically consider custom usage analytics metadata keys that start with the context_ prefix.

Other relevant results which aren’t seen in a specified context aren’t promoted by Coveo ML models. However, their overall ranking score may still be higher than the contextually promoted ones when they’re popular.

A query can carry more than one context key/value pair, in which case the ranking score boosts associated with each key/value context pair are combined.

Note

Coveo ML models automatically ignore statistically irrelevant contexts (contexts where a trend can’t be found).

Leading practices

Consider the following guidelines when leveraging custom context:

For the same queries, successful results are significantly different depending on the context key/value pairs.
Example
The context can be the user role. The authenticated users on your software product documentation site play one of the following role relative to your product:
- User - Uses the product.
- Administrator - Installs, configures, and supports the product.
- Developer - Writes code to customize or interact with your product.
Because users are authenticated, at query time you have a method to get the user role.
You can clearly identify and send the appropriate static or dynamic key/value pair with each query.
While contexts can be combined, use only the few most significant context keys.
Examples
- On your client community, you can send the following contexts since they’re different for each client:
  
  User role
  
  User department
  
  Product categories they already own
  
  User country (useful when items are different from one country to the other)
- You have many employees using your agent panel. Therefore, you want to pass information about the role, department, and level of your agents to categorize or group them.
  
  When logging usage analytics events, your developer includes, in the customData property of the request body, key-value pairs such as:
  
  "context_role":"<context_role>"
  
  "context_department":"<context_department>"
  
  "context_level":"<context_level>"
  
  where:
  
  <context_role> is the role of the agent sending the request.
  
  <context_department> is the department of the agent sending the request.
  
  <context_level> is the level of the agent sending the request.
Increasing the number of context combinations dilutes the context-specific effect. Reduce the number of key/value pairs even more when the level of search activity is low.

Example

Your Coveo-powered customer portal search page serves about 500,000 search events per day. These events provide plenty of activity from which Coveo ML models can learn for a few contexts, each with a few values.

By contrast, your Coveo-powered employee portal search page serves less than 1,000 search events per day (this is normal, as only a few hundred employees can access it). With much less data to learn from, Coveo ML models may only be effective for one significant context key, with only a few values.
Each context key should have a limited number of possible values, less than 10 being recommended.

Example

Your product popularity vary notably from one country to the other, so you guess using the search page user country of origin as a context will help Coveo ML models return more relevant content for customers of each country.

The effect of the context will probably be notable if your customers are from only a few countries, but may be diluted if they come from 100 countries.
The following aspects must not be used as custom context keys. They’re automatically passed by the Coveo UI libraries (Atomic and Headless) with each query and are taken into account by the default Coveo ML models:
- Language - The language of the search interface.
- Search Hub - The name you give to a specific search instance.
- Interface (Tab) - The different search page tabs in your search hub.
- Is Guest
- Is Anonymous
Example

Coveo powers the search pages in your English-only employee portal as well as in your multi-language customer portal.

In the Spanish customer portal, the output of the Coveo ML models should only consider what other customers have searched for in this portal beforehand, not searches made in the employee portal.

Leverage custom context

Define the context key/value pairs that you plan to leverage.

It’s important to pick key/value custom context pairs for which you can get appropriate values in your code and provide good search result differentiation (see Custom context leveraging leading practices).
Make sure that appropriate context key/value pairs that you defined are passed by your search interface with each query:
- Standard search events (for Coveo ML Automatic Relevance Tuning (ART) and Dynamic Navigation Experience (DNE)).
  
  For Coveo Atomic library search interfaces, you can access Headless through Atomic and send context using the Headless context controller.
  
  In Coveo Headless library search interfaces, refer to modify the metadata to send with UA events to learn how to specify custom context for each UA event. To use the context Headless controller to send context, see Sending context with Headless.
- View events (for Recommendation components).
  
  View events are required by Content Recommendation (CR) models. You must pass custom context key/value pairs in the view events, and have your custom context key names start with the context_ prefix.
  
  Note
  
  With the new Event API, you would include custom context only when making queries, not when logging events yourself.
Create or edit Coveo ML models.

Existing or new Coveo ML models automatically take advantage of custom context values. They’re passed, as described in the previous steps, when they’re trained or retrained, so there’s no custom-context-specific configuration to do on Coveo ML models.

Create Coveo ML models, if not already done.

Try to measure the impact of custom contexts.

There are no direct methods to measure the impact of the custom contexts on the output of Coveo ML models. However, you can create analytics reports to look at certain quality metrics. For example, Clickthrough or Click Rank as a function of context dimensions.

Create a dimension for each of your custom context keys.

Note

When some custom context key/value pairs have been passed by your search interface, in the Add a Dimension panel, the API name parameter automatically proposes custom context keys. The key is prefixed with context_.

For example, when your custom context key is userRole, the proposed API name value is context_userRole.

Validate that your Coveo ML model has been trained since you started to send custom context.
Create a report with the metrics of your choice filtered by your context dimensions.

Sending context with Headless

Headless can be used to send context with requests made to Coveo. Headless engines include a Context controller, which allows you to add context to the engine. The controller sends any context added here with all requests, including Search and UA requests.

Additionally, if you wish to send specific context based on certain events, you should send context using preprocessRequest. For more information, see Modify requests and responses.

Using the example of the product documentation site, set the role and region context to be sent as part of UA events through the Context Headless controller.

import { 
  SearchEngine,
  buildContext
} from '@coveo/headless';

export function setupContext(headlessEngine: SearchEngine) { 
  const context = buildContext(headlessEngine!);
  context.set({ 
      'region': 'Canada',
      'role': getRole(),
    }
  );
  return headlessEngine;
}

	Import `SearchEngine`, indicating the type of Headless engine for context addition, and `buildContext`, a method essential for initializing the `context` controller.
	The `setupContext` function, takes as input the `SearchEngine` Headless engine you wish to set context on. To understand how to create and configure a Headless engine, see `Configure a Headless Engine`.
	Context values can be set statically through `string` values using the `set()` method. For example, if you want gather context for your Canadian site, static context ensures that the usage analytics will include only this specified region. Context can also be set dynamically through business logic. For example, a custom `getRole()` method is created and implemented in the organization to retrieve the user’s role. In this case, the usage analytics event will be sent with the user’s corresponding role.