Use automatic boosting

This is for:

Developer System Administrator
Warning
Legacy feature

This article pertains to achieving relevance with the Coveo Hive framework. Coveo Hive is now in maintenance mode.

See Achieve relevance for guidance on leveraging Coveo Platform relevance features with the Coveo Atomic library.
Important

This feature was meant primarily for old on-premises implementations and should no longer be used. Coveo Machine Learning (Coveo ML) now drastically improves the quality of results provided to users automatically, without drawing any information from Sitecore pattern and profile cards.

Automatic Boosting is a feature that can help you personalize your search components by leveraging information coming from your user profiles and patterns. It automatically boosts search results according to the visitor pattern.

Requirements

This tutorial assumes that:

  • You have a running Sitecore instance with xDB installed.

  • You have the Enterprise edition of Coveo for Sitecore.

  • You’ve indexed documents with the parameter indexAnalyticsFields set to true (see About the Coveo Search Provider configuration file).

Note

Using the Automatic Boosting requires that you’ve defined profiles, profile cards, and pattern cards in your Sitecore instance. Remember to set the minimum and maximum values on every profile key. Items should also have profile cards assigned to them if you want them to be boosted.
36176374

Enabling automatic boosting using the Coveo Hive framework

To enable automatic boosting

  1. Open your Coveo-powered search page in the Sitecore Experience Editor.

  2. Select the UI Header placeholder.

  3. Click + Add here.

  4. Select the Automatic Boosting rendering.

  5. In the Select the Associated Content dialog, select Create New Content.

  6. Give your data source a name and save it in an appropriate location in your data source branching.

  7. In the Automatic Boosting component floating toolbar, select the Edit the rendering’s data source option. It should be the leftmost option.

    EnableAutomaticBoosting

  8. In the Query Ranking section, select Enable automatic boosting. Options will appear under the Enable automatic boosting checkbox.

  9. Select any of the options that appear under the Enable automatic boosting checkbox. In this example, the Focus option is selected.

  10. Click OK in the dialog to accept the default boosting settings.

    AutoBoostingConfiguration

  11. Save the changes to your search page in the Experience Editor.

Understanding how it works

Automatic Boosting generates a Query Ranking Function (QRF) in your queries based on the current visitor pattern.

For example, the current visitor pattern identified for the Visit Profile profile is called Bob the businesstraveler, and is defined as such:

36176377

To understand how it works, remember that patterns are a combination of profile keys. The QRF is based on those profile keys.

The generated QRF uses the profile keys percentage value. For example, the value of the Bob the business traveler pattern for the Duration profile key is 8 out of 10, so the percent value is 0.8 (80%).

Every item with a Duration profile key with a percentage value close or equal to 0.8 will be boosted. The closer they are, the more they’re boosted.

The boosting is done following a Gaussian (bell shaped) function that you can adapt with the different settings.

The following graph is an example of what the function looks like for the Duration profile key with the default settings:

36176378

Looking at the graph, you can see that an item with a Duration profile key percentage of 0.8 would be boosted by 80 points (see Boosting Settings below to understand how the maximum value, in this case 80, is calculated).

Items with 0.7 or 0.9 would be boosted by approximately 48 points, items with 0.6 or 1 would be boosted by approximately 11 points, and items with further values wouldn’t be boosted significantly.

A graph like this is applied to each profile key and the results are added together in the QRF. Here is an example of a full QRF generated by the Bob the business traveler pattern card:

$qrf(expression:'exp(-(@fvisitz32xprofilez32xbusinessz32xkeyz32xpercent93146-1)^2/(2*0.01))*150 + exp(-(@fvisitz32xprofilez32xcouplesz32xkeyz32xpercent93146-0.1)^2/(2*0.01))*10 +
exp(-(@fvisitz32xprofilez32xdurationz32xkeyz32xpercent93146-0.8)^2/(2*0.01))*80 + exp(-(@fvisitz32xprofilez32xnightlifez32xkeyz32xpercent93146-0.4)^2/(2*0.01))*40 +
exp(-(@fvisitz32xprofilez32xrepeatz32xvisitsz32xkeyz32xpercent93146-0.1)^2/(2*0.01))*10 + exp(-(@fvisitz32xprofilez32xtourismz32xkeyz32xpercent93146-0.2)^2/(2*0.01))*20', normalizeWeight: True)

You can see each profile key that isn’t zero in the pattern card represented in the QRF.

You can also see the normalizeWeight parameter at the end of the equation. This is always true, as it prevents boosting from being too small or too big. More specifically, it maps the complete value domain to the 0 to 600 range.

Boosting settings

Three settings are available to help fine-tune your automatic boosting.

Boosting Influence (%)

This setting is used to calculate the maximum value of the boosting on a profile key (maximum value = Profile key percentage x Boosting Influence). This explains the 80 in the example above.

However, since the values are normalized, the setting doesn’t change anything if you only have one profile enabled.

This setting is useful if you activate more than one profile, and want one of them to have more influence on the boosting. For example, if you have Visit Profile and Score enabled, but you want Visit Profile to be more important, you can let the Boosting Influence of Visit Profile at 100, but put the Boosting Influence of Score at 50. That way, the boosting influence from the Visit Profile will be twice as important as the one from Score.

Boosting weight range

This is an important setting to customize, as the default value isn’t ideal for every situation.

This setting allows you to be more or less restrictive about the boosting. A larger value allows you to boost profile keys with percentages further from the pattern, and a smaller value makes your boosting affect only items with the exact same profile key percentage as the pattern. This affects the width of the graph.

Using the same example as above, you can change the Boosting Weight Range to 2, making the graph look like this:

36176379

Here, a profile key with a percentage value of 0.8 would still be boosted by 80 points, but 0.7 and 0.9 would now be boosted by approximately 62 points, 0.6 and 1 by approximately 29 points. A percentage value of 0.5 would now yield 8 points.

You could also narrow it if you only want 0.8 to be boosted by changing the value to 0.01, making the graph look like this:

36176380

It’s possible to test and see the look of the function with different values for the Boosting Weight Range. To see the equation used to draw the graphs for the previous example, see the Wolfram|Alpha diagram.

By editing some values, you can adapt it to your situation and see what the graphs look like. Here is the equation you should see:

plot exp(-(x-0.8)^2/(2*1/100))*80 x from 0 to 1 y from 0 to 80

Here are the values to edit:

  • The 0.8 is the profile key percentage value from your pattern card. Be sure to modify the maximum value if you edit this to have coherent results.

  • The 1 in the equation is the Boosting Weight Range.

  • The 80 in the equation is the maximum value. It should always be equal to the profile key percentage value x Boosting influence.

  • The x from 0 to 1 y from 0 to 80 section is simply a display setting. Modifying the maximum value of the y parameter to fit the maximum value allows you to see the complete graph.

Dominant keys boosting influence (%)

The dominant key of a pattern is the profile key with the highest value, and with a percent value of at least 0.5. The Dominant Key Boosting Influence increases the maximum boost value of the dominant profile key by the amount specified. Its default value is 50%.

For example, when looking at the Bob the business traveler pattern above, you can see that the dominant profile key is Business. Normally, the maximum value would be 100 (1 * Boosting Influence), but you can see in the QRF that the maximum value is 150. That’s because a 50% boost was added (100 + 100 * 50% = 150).

Testing the automatic boosting

Note

You may notice that enabling Automatic Boosting doesn’t change anything in your search results ranking. This is most likely because Sitecore hasn’t recognized any visitor pattern yet. A visitor pattern is recognized when visiting pages that correspond to an item with an assigned profile card.

The fastest way to test your automatic boosting is to use the Experience Explorer.

Important

Remember to publish your search page or search component before using it.

In this example, the Business item was clicked a few times, and Sitecore recognized the pattern Bob the business traveler. With the automatic boosting, the item with the Business profile appears first.

36176385
Note

The generated QRF is based on the pattern card item (Bob the business traveler in that case) and not on the values that you see in the Viewer tab. The Viewer tab simply tells you the keys that have been calculated, but the real pattern is the card itself.

Gathering the ranking information on results

If you want more information on the ranking of each result in your result template, you can add &debug=1 at the end of the URL of the search page, before the # if you had done a query.

Then, when opening your browser developer console, you should see the details of the ranking generated for each result:

36176386